Configuring Signed JWT Authentication for the Workvivo API

Signed JWT (JSON Web Token) authentication provides a secure way for organizations to connect their applications to the Workvivo Customer API without relying on long-lived API keys.

With Signed JWT authentication, your application generates a unique, short-lived token for each API request. Workvivo verifies the token using your organization's public key, while your private key remains securely stored within your own infrastructure.

This approach is particularly useful for enterprise integrations that require additional security controls, token expiration, and independent key rotation.

Device(s): Desktop

Roles / Permissions: Developer, IT Administrator

Availability: Available to organizations with Customer API access enabled. Contact your Workvivo point-of-contact if API access has not been activated.

Understanding Authentication Methods

The Workvivo Customer API supports two authentication methods:

• API Key: Workvivo generates a static API key that your application includes in each request.
• Signed JWT: Your application generates and signs a short-lived token for each request, which Workvivo validates using your public key.

Both methods are managed through API Keys & JWT Settings in the Admin Hub.

Each application uses one authentication method, although an organization can have applications using either method.

Before You Begin

Before configuring Signed JWT authentication, ensure that:

• Customer API access is enabled for your organization.
• You have the Developer role in Workvivo.
• An IT Administrator is available to configure JWT Settings.
• Your application can generate and sign JWTs using RS256.
• Your infrastructure can securely store private keys.
• Your application servers have accurate, synchronized clocks.

Important: Workvivo does not allow for clock drift. Tokens with future iat or nbf values may be rejected.

Step 1: Access API Keys & JWT Settings

1. Log in to Workvivo on your desktop.
2. Navigate to Admin Hub > Platform > API Keys & JWT Settings.
3. Locate the JWT Settings option.

This page allows you to manage Customer API applications using either API Key or Signed JWT authentication.

Step 2: Configure JWT Settings

Before creating a Signed JWT application, configure how Workvivo will validate your signed tokens.

1. Click JWT Settings.
2. Locate the Public Key section.
3. Select the appropriate Key Type.

Two options are supported:

JWKS

• Host your organization's public keys at an externally accessible JWKS endpoint.
• Provide the public key URL in Workvivo.
• Supports both Customer API authentication and JWT SSO.
• Allows key rotation without manually updating the public keys in Workvivo.

JWKS Hosted

• Paste your public keys directly into Workvivo in JWKS format.
• Supports Customer API authentication only.
• Requires manually updating the stored public keys when rotating keys.

Important: The PEM option is intended for legacy API JWT authentication and cannot be used with Signed JWT.

The Key Type setting is shared with JWT SSO. If your organization uses both JWT SSO and Signed JWT Customer API authentication, select JWKS.

Configure Your Public Key

If using JWKS:

1. Select JWKS.
2. Enter your publicly accessible JWKS URL.
3. Ensure the endpoint returns a valid JSON Web Key Set.

Example:

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "kid": "<your-key-id>",
      "n": "<your-public-key-modulus>",
      "e": "AQAB"
    }
  ]
}

If using JWKS Hosted:

1. Select JWKS Hosted.
2. Paste your public keys into the provided field.
3. Ensure each key contains a valid kid and alg.

Important: Never upload or paste your private key into Workvivo. Only your public keys should be shared.

Configure Issuer and Audience

1. Open the Customer API tab within JWT Settings.
2. Configure the following values:

• Issuer (iss): Identifies the organization or service generating the JWT.
• Audience (aud): Identifies the intended recipient of the JWT, such as the Workvivo Customer API base URL.

The values configured here must match the values included in every JWT your application generates.

Important: The Customer API Audience cannot be your Workvivo organization domain, as this is reserved for JWT SSO.

If your organization already uses Okta JWT, retain the existing Issuer and Audience settings and use those values in your Signed JWT tokens.

3. Click Save.

Once successfully configured, the Customer API tab will display Configured.

Step 3: Create a Signed JWT Application

1. Return to Admin Hub > Platform > API Keys & JWT Settings.
2. Click Add New App.
3. Enter a name for your application.
4. Under Authentication Method, select Signed JWT.
5. Select the permissions required by your integration.
6. Click Save.

Application names can contain letters, numbers, dashes, and underscores, up to 60 characters. Spaces are not supported.

Important: An application's authentication method cannot be changed after creation. To use a different method, create another application.

Step 4: Review Your Application's JWT Identity

After creating the application:

1. Locate the application in the list.
2. Click JWT Identity.

The JWT Identity page provides the information required to authenticate API requests, including:

• Request headers
• Application identity claims
• Organization settings
• Sample JWT payload
• Example API request

Workvivo does not generate Signed JWT tokens for your application. Tokens must be generated and signed within your own infrastructure.

Step 5: Generate and Sign a JWT

Your application must generate a new signed JWT for each API request.

Each token must include the required claims:

Example JWT payload:

{
  "version": "strict",
  "iss": "https://yourcompany.com",
  "sub": "app",
  "aud": "https://api.workvivo.com",
  "organisation_id": 1234,
  "iat": 1760000000,
  "nbf": 1760000000,
  "exp": 1760000300,
  "state": "8f14e45f-ceea-467f-a0e6-4c3f9b2d1a7e",
  "email": "1780492723-a1B2c3D4e@my-integration.com"
}

The JWT must be signed using RS256, with the private key corresponding to the public key configured in Workvivo.

The JWT header must contain the correct kid so Workvivo can identify the public key used to verify the signature.

Important: Each token can only be used once. Generate a new token with a unique state value for every request.

Step 6: Authenticate Your API Request

Once your JWT has been generated and signed, include it in the following HTTP headers:

Example request:

curl -X GET "https://api.workvivo.com/v1/users?take=1" \
  -H "workvivo-id: 1234" \
  -H "x-workvivo-jwt: <YOUR_SIGNED_JWT>" \
  -H "Accept: application/json"

Use the Customer API Base URL displayed in your organization's API settings.

Unlike API Key authentication, Signed JWT requests do not use the Authorization: Bearer header.

Managing and Rotating Your Keys

Signed JWT authentication allows organizations to manage and rotate their own signing keys.

To rotate keys:

1. Publish your new public key alongside the existing key.
2. Update your application to sign JWTs using the new private key.
3. Ensure the JWT header includes the new key's kid.
4. Once the old key is no longer being used, remove it.

If using JWKS, Workvivo can retrieve updated keys from your configured endpoint.

If using JWKS Hosted, update the public keys manually in JWT Settings.

Important: Removing an existing public key may cause tokens signed with that key to fail authentication, even if they have not expired.

Troubleshooting Signed JWT Authentication

If your application encounters authentication issues, review the following common causes.

401 Unauthorized

• Confirm JWT Settings are fully configured.
• Verify that the Issuer and Audience match the configured values.
• Ensure the JWT contains the correct application identity and organization ID.
• Check that the token has not expired or already been used.
• Confirm the JWT is signed with the correct private key.
• Verify the kid matches an available public key.
• Check that your application server's clock is synchronized.

403 Forbidden

• Confirm that the application has the required API permissions.
• Ensure you're calling a supported Customer API endpoint.
• Signed JWT application tokens cannot access User Contextual API endpoints under /v1/jwt/.

Unable to configure JWT Settings

• Confirm you have the IT Administrator role.
• Verify that the selected Key Type is supported.
• Ensure the Audience is not set to your Workvivo organization domain.

Unable to access API Keys & JWT Settings

• Confirm that your account has the Developer role.
• Verify that Customer API access is enabled for your organization.

Additional Information

• Refer to the Workvivo Customer API documentation for available endpoints and permissions.
• Review the Customer API Quick Start guide for additional authentication examples.
• Refer to Handling Errors for guidance on API error responses and troubleshooting.

If Customer API access has not been enabled for your organization, contact your Workvivo Customer Experience Manager for assistance.