Set up authentication with Okta

This guide walks through configuring Okta to authenticate against the Moveworks Conversations API. By the end you will have Okta issuing access tokens for your users, and your application successfully calling the Conversations API on their behalf.

How authentication works

The Conversations API uses a token exchange model. Your application obtains an access token from Okta, exchanges it for a Moveworks bearer token, and uses the Moveworks bearer on Conversations API requests.

This guide covers user-facing clients where a real person signs in through Okta. For a backend service that acts on behalf of users without an interactive sign-in, use service-to-service authentication instead.

Prerequisites

Confirm the following before you start:

• Your account team has enabled the Conversations API for your org, and you have created the chatbot and recorded its Bot Name (used in the Assistant-Name header on every API call). See Create the Conversations API chatbot.
• You have admin access to the Moveworks Admin Portal (https://{org}.moveworks.com).
• You have admin access to your Okta org.
• The identifier your Okta sub claim will carry resolves against your Moveworks user roster. This guide assumes sub carries the user’s email address, which is the default on a Custom Authorization Server and matches the email on the user’s Moveworks profile. If your sub carries a different identifier, see the alternative in step 2.

Step 1: Create the Okta authorization server

In the Okta Admin Console, go to Security → API → Authorization Servers → Add Authorization Server.

• Name: any descriptive label (for example Moveworks-CAPI).
• Audience: enter any placeholder for now if you plan to use a Moveworks-generated audience; you’ll set the real value in Step 3.1. If you intend to keep an audience value you already use, enter it here and register the same value in Moveworks in Step 2.
• Description: optional.

Click Save. Once created, capture two values from the auth server. You’ll paste both into Moveworks in Step 2.

Step 2: Register the credential in Moveworks

In the Moveworks Admin Portal, go to https://{org}.moveworks.com/http-connectors/connector_studio/home → Credentials → Create Credential. Set the fields as follows.

Click Save and then Publish. Moveworks displays three values back to you:

• Subject: Moveworks-internal ID for the credential.
• Audience: the credential’s audience. If you left the field blank, this is the unique value Moveworks generated (format: api.moveworks.ai/{uuid}); copy it to paste into Okta in Step 3. If you entered your own value, confirm it displays exactly as you entered it.
• Public Key 1 - ID: Moveworks-side identifier for the key it fetched from your Metadata URI. No action needed.

Step 3: Finish configuring the Okta authorization server

Return to the Okta Admin Console, Security → API → Authorization Servers, and open the authorization server you created in Step 1.

(appuser != null) ? appuser.userName : app.clientId

The access policy rule that links this authorization server to your OAuth application comes in Step 4.4, after you create the app.

Step 4: Create the Okta OAuth application

In the Okta Admin Console, go to Applications → Applications → Create App Integration. The dialog asks for two things:

1. Sign-in method — choose OIDC - OpenID Connect. (The other option, API Services, issues tokens that represent the app itself rather than a signed-in user, which does not fit the Conversations API’s per-user model and is not covered by this guide. For backend integrations, use service-to-service authentication.)
2. Application type — pick one:
   • Single-Page Application for a browser-based client (React, Vue, Angular, etc.). Uses Authorization Code + PKCE.
   • Web Application for a server-side client with a client secret. Uses Authorization Code.
   • Native Application for a desktop or mobile app.

Click Next.

Note your app’s Client ID. You need it in the next step. Web Applications also have a Client Secret; SPAs do not.

Step 5: Get an Okta access token

In production, your app’s Okta SDK handles the browser redirect, code exchange, and token capture automatically. For manual testing, use an OIDC playground such as oauth.tools, or run a local PKCE flow with a script and register http://localhost:PORT/callback as a redirect URI on your Okta application.

However you run the flow, the response includes an access_token field. Copy that value; it is your Okta access token. Decode it (for example at jwt.io) and confirm:

• iss matches the Issuer you registered in Step 2 exactly.
• aud matches the Audience on your Moveworks credential (the generated api.moveworks.ai/{uuid} value, or the custom value you registered).
• sub matches the identifier expected by your Moveworks user roster.

If any of these do not match, the exchange in Step 6 will fail. Re-check the corresponding fields in Steps 2 and 3.2 before continuing.

Step 6: Exchange the Okta token for a Moveworks bearer

Your application must complete this step before making any Conversations API call.

curl -X POST "https://api.moveworks.ai/oauth/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
  --data-urlencode "assertion=<OKTA_ACCESS_TOKEN>"

A successful response:

{
  "access_token": "mwt_...",
  "expires_in": 3599,
  "token_type": "Bearer"
}

The mwt_... value is your Moveworks access token. It represents the user resolved from the Okta sub claim, expires in about an hour, and is the bearer you use on every Conversations API call.

Cache and refresh: cache this token for the duration in expires_in (typically ~1 hour). When it expires, get a fresh Okta token and repeat this exchange. Do not exchange on every API call; that pattern will hit rate limits.

Step 7: Call the Conversations API

Use the Moveworks bearer from Step 6 on every request. Include the Assistant-Name header (the Bot Name of the chatbot you created).

curl -X POST "https://api.moveworks.ai/assistant/v1/conversations" \
  -H "Authorization: Bearer <MW_ACCESS_TOKEN>" \
  -H "Assistant-Name: <YOUR_BOT_NAME>" \
  -H "Content-Type: application/json" \
  -d '{"title": "Test conversation"}'

A 201 response with a conversation_id confirms the whole chain works end to end.

Troubleshooting

401 UNAUTHORIZED with Token validation failed when calling /assistant/v1/*.

Check that your Authorization: Bearer value is the Moveworks bearer from Step 6 (starts with mwt_), not the raw Okta access token (starts with eyJ). If you’re already sending mwt_... and still hitting this error, the bearer has likely expired; repeat Step 6 with a fresh Okta token.

401 UNAUTHORIZED with Token validation failed at the exchange endpoint (/oauth/v1/token).

The Okta token was received but Moveworks rejected it. Decode the Okta token and confirm:

• iss matches the Issuer field on your Moveworks credential (byte-for-byte, no trailing slash, correct case).
• aud matches the Audience field on your Moveworks credential exactly (whether Moveworks-generated or the custom value you registered in Step 2).
• sub matches the identifier your Moveworks user roster resolves. With Identifier Type set to Email, this must be the email address on the user’s Moveworks profile. If sub is an Okta internal user ID starting with 00u, you’re looking at the ID token, not the access token. Decode the access token instead. If sub on the access token is still 00u..., revisit Step 3.2 to override the default expression, or use the IdP alternative in Step 2 to match that ID against an identity integration.
• The credential in Moveworks Setup is Published (not draft).
• The token has not expired (exp is in the future).

Okta rejects the token request before Moveworks sees it (error at /authorize or /token).

Okta’s access policy or user assignment blocks the token issuance. Revisit Step 4.2 (assign the user to the app) and Step 4.4 (access policy rule allowing your app + grant type + scopes).

aud claim comes out as api://default in the token.

Your token is being issued by Okta’s pre-built default authorization server rather than the one you created in Step 1. Either point your app’s token requests at the right authorization server, or, since the Moveworks credential accepts any audience value, register api://default as the credential’s Audience. A dedicated authorization server with a distinct audience is easier to debug.

401 INVALID_JWT, “Client credentials not found”, on a call to /oauth/v1/token.

Moveworks locates your credential by the iss and aud pair on the incoming token, so this means that pair matched no registered credential. Compare the decoded aud against the credential’s Audience and the decoded iss against its Issuer, exactly. Also confirm the credential is Published and that you are calling the base URL for your data center.

401 INVALID_JWT, “JWT signature verification failed”, on a call to /oauth/v1/token.

The credential was found, so the issuer and audience are right. Confirm the credential’s metadata URL points at the same Okta authorization server that minted the token, so that Moveworks fetches the matching signing key.

User is authenticated but Conversations API responses look wrong or empty.

The sub claim resolved to a Moveworks user, but potentially the wrong one. Confirm the email address in sub is the one on the intended user’s Moveworks profile, and that the same address is not present on more than one profile. If your Okta emits a different email or login format than what is on the Moveworks user record, adjust the Okta sub claim mapping (Step 3.2).

Summary of what you configured

For interaction patterns (polling and streaming) and the full API contract, see the Conversations API reference.