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 Moveworks tenant is provisioned for the Conversations API and your account team has provided the Bot Name (used in the Assistant-Name header on every API call).
• 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 (commonly the user’s email or login) resolves against your Moveworks user roster.

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:

1
{
2
  "access_token": "mwt_...",
3
  "expires_in": 3599,
4
  "token_type": "Bearer"
5
}

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 (your Bot Name from your Moveworks account team).

$
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. 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.
• 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.

invalid_audience on a call to /oauth/v1/token.

Your Okta token’s aud does not match what’s registered on your Moveworks credential. Compare the decoded aud against the Audience field on your Moveworks credential exactly.

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

The sub claim resolved to a Moveworks user, but potentially the wrong one. Check that the identifier in sub matches the user’s channel entry with integration_id: conversations_rest_api in Moveworks. If your Okta emits a different email or login format than what’s on the Moveworks user record, adjust either the Okta sub claim mapping (Step 3.2) or the user’s channel entry.

Summary of what you configured

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