Set up service-to-service authentication

This guide covers authenticating a backend service to the Moveworks Conversations API, so that service can make requests on behalf of any provisioned user in your Moveworks tenant. Your backend generates and signs the JWT locally, then exchanges it for a Moveworks bearer token.

When to use this

Use this pattern when a trusted backend system (test harness, batch worker, monitoring bot, scripted integration) needs to make Conversations API calls on behalf of an already-known user, and there is no interactive user browser flow available to obtain a token.

Use one of the interactive user guides instead when:

• Real end users sign in through your application and each request represents that specific signed-in user. See Set up authentication with Okta or Set up authentication with Azure AD (Entra ID).

The trade-off:

How it works

Your backend service holds an RSA private key. The matching public key is registered as a credential in your Moveworks tenant. For each API call you want to make on behalf of a user:

1. Your backend builds a short-lived JWT that names the user in the sub claim and signs it with the private key.
2. Your backend exchanges the signed JWT at POST /oauth/v1/token for a Moveworks bearer token.
3. Your backend uses that bearer token on Conversations API calls. The bearer is scoped to the user in sub.

The private key is a tenant-wide credential. Any process holding it can obtain a bearer for any user in the tenant. Treat it accordingly (see Security).

Prerequisites

• 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.
• Admin access to your Moveworks Admin Portal (https://{org}.moveworks.com).
• A Unix-like environment (or WSL / OpenSSL for Windows) to generate keys.
• Ability to run a backend runtime that can sign JWTs (any language with an RS256 JWT library works; the samples in this guide are Python).
• The set of users your backend will act on behalf of are already resolvable against your Moveworks user roster.

Step 1: Generate an RSA keypair

On the machine that will run your backend service, generate a 2048-bit RSA keypair and lock down the private key permissions.

openssl genpkey -algorithm RSA -out private.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -in private.pem -pubout -out public.pem
chmod 600 private.pem

You will register public.pem with Moveworks in step 2 and keep private.pem on your backend.

Step 2: Create the JWT OAuth credential in Moveworks

In the Moveworks Admin Portal, go to https://{org}.moveworks.com/http-connectors/connector_studio/home → Credentials → create a new credential.

Save and then Publish the credential; the token exchange fails while it is still in draft. Moveworks displays a Key ID (KID) value; copy it. You will include it in every JWT header.

Step 3: Sign the JWT and exchange for a bearer

Your backend performs two operations per request (or per short-lived cache window):

1. Build a JWT with the user’s identifier in sub, sign with the private key.
2. Exchange the signed JWT at Moveworks’ token endpoint for a bearer.

Python example

Install dependencies:

pip install pyjwt cryptography httpx

Sign the assertion and exchange it for a bearer:

import time
import uuid
import jwt          # PyJWT
import httpx
PRIVATE_KEY = open('private.pem').read()
ISS = 'capi-backend.acme.com'            # matches the credential's Issuer field
AUD = 'capi-backend.acme.com'            # matches the credential's Audience field
KID = '<KEY_ID_FROM_MOVEWORKS>'          # from the credential creation response
TOKEN_URL = 'https://api.moveworks.ai/oauth/v1/token'
def sign_assertion(user_email: str, ttl_seconds: int = 300) -> str:
    now = int(time.time())
    claims = {
        'iss': ISS,
        'sub': user_email,
        'aud': AUD,
        'iat': now,
        'exp': now + ttl_seconds,
        'jti': str(uuid.uuid4()),
    }
    return jwt.encode(
        claims,
        PRIVATE_KEY,
        algorithm='RS256',
        headers={'kid': KID},
    )
def mint_bearer(user_email: str) -> str:
    assertion = sign_assertion(user_email)
    response = httpx.post(
        TOKEN_URL,
        data={
            'grant_type': 'urn:ietf:params:oauth:grant-type:jwt-bearer',
            'assertion': assertion,
        },
        timeout=15.0,
    )
    response.raise_for_status()
    return response.json()['access_token']
bearer = mint_bearer('alice@acme.com')

What each claim does

The kid header identifies which registered public key Moveworks should use to verify the signature.

Caching the bearer

The exchange response includes expires_in (typically ~1 hour). You can cache the returned bearer per user for its lifetime and only re-mint when it expires or nears expiration. Refresh proactively (for example, at 90% of expires_in) so long-running operations do not fail mid-flight.

Step 4: Call the Conversations API

Use the bearer on any Conversations API endpoint. Every request must include the Assistant-Name header (the Bot Name of the chatbot you created) and the Authorization header.

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

A 201 response with a conversation_id confirms the integration works end to end. To switch to a different user on a subsequent request, sign a new assertion with a different sub and exchange it for a new bearer.

Step 5: Validate

Confirm end to end before wiring it into production:

1. Sign an assertion for a known-good test user in your roster and decode it (for example, at jwt.io) to confirm iss, aud, sub, iat, exp, jti, and the kid header are all populated as expected.
2. Exchange the assertion at /oauth/v1/token. A 200 response with an access_token means the signature verified and the user resolved. Common failure modes:
   • 401 INVALID_JWT, “Client credentials not found”: the iss and aud pair on your assertion matched no registered credential. Moveworks locates the credential by that pair, so check both against the credential exactly, confirm it is Published, and confirm you are calling your data center’s host.
   • 401 INVALID_JWT, “JWT signature verification failed”: the credential was found, so iss and aud are right. The kid header doesn’t match a registered key, or the private key you signed with isn’t the pair of the registered public key.
   • Generic post-verification failure: the sub value doesn’t resolve to a user in the roster. Confirm the identifier your backend sends in sub matches the Identifier Type on the credential: with Email, it must be the email address on the user’s Moveworks profile; with IdP, it must match the value stored under the integration ID you registered.
3. Create a conversation with the returned bearer as above. A 201 with a conversation_id closes the loop.

Security

Recommended handling:

• Store the private key in a secret manager (AWS Secrets Manager, Google Secret Manager, HashiCorp Vault, etc.). Do not commit it to source control, embed it in application bundles, or store it on developer laptops beyond initial setup.
• Restrict which services can read the private key. Only the specific backend process that needs to mint bearers should have access.
• Log every action taken on behalf of each user in your own audit trail. From Moveworks’ perspective, actions taken by your backend on behalf of a user are indistinguishable from actions that user performed themselves. Your own audit trail is the only source of truth for which system initiated the call.
• Rotate the credential if the private key is plausibly exposed. Generate a fresh keypair, register the new public key as a new credential, cut your backend over, then delete the old credential.
• Do not use this credential type for user-facing product integrations where end users obtain tokens directly. Use the interactive user auth guides for those flows.

Summary

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