Skip to main content
A 401 can mean two different things. Suki rejected your Partner Token at Register or Login, or a later REST or WebSocket call sent a missing, expired, or invalid Suki Token (sdp_suki_token). Read the error message before you change credentials.

โ€‹
Which 401 you have

On Partner APIs, Login returns suki_token. Send that value as the sdp_suki_token header on later REST and WebSocket calls. A Partner Token alone is not enough for session, stream, or content endpoints.

โ€‹
Partner Token validation failed

Suki validates the Partner Token (JWT) with your Partner ID and the public keys you registered (usually a JWKS URL). Validation fails when the JWT is expired, missing required claims, malformed, or signed with a key Suki cannot verify.

โ€‹
Required JWT claims

Confirm these claims are present and valid before you call Suki (decode with jwt.io if needed):
  • exp - Token expiration time (Unix timestamp). The token must not be expired when you send it.
  • iss - Token issuer (usually your identity provider URL or identifier).
  • aud - Token audience (who the token is intended for).
  • User identifier - A claim that uniquely identifies the user, such as sub, email, or a custom claim like userId. During onboarding you tell Suki which field is primary.
The Partner Token must be signed with RS256 and follow standard JWT format: header.payload.signature.

โ€‹
Fix Partner Token failures

1

Confirm field names for your integration

Partner APIs: Send partner_id and partner_token in the Register and Login request body. For Bearer and Single Auth Token partners, also send provider_id when required.SDKs: Pass partnerId and partnerToken (for example through SukiAuthManager or the Headless auth hook).
2

Decode and inspect the JWT

Check exp, iss, aud, and the user identifier claim you registered during onboarding. Fix empty or null identifier values.
3

Verify signing keys

Confirm your JWKS URL (or other public-key method) is reachable over HTTPS and that the kid in the JWT header matches a key in that JWKS set. After key rotation, keep old keys available during the transition.
4

Match Partner ID to onboarding

Use the Partner ID Suki issued for your account. A wrong Partner ID returns 400 with โ€œUnknown partner identifierโ€, not a successful token exchange.

โ€‹
invalid_sdp_token on later calls

After Login succeeds, Partner API calls authorize with the Suki Token. The common error id is invalid_sdp_token (401): missing, expired, or invalid sdp_suki_token.
1

Confirm Login succeeded

Call Login and read suki_token from the response. Do not reuse a Partner Token as sdp_suki_token.
2

Send the documented header

Set the sdp_suki_token header on subsequent REST and WebSocket requests. Use the same environment host for Login and for those calls.
3

Refresh before or after expiry

The Suki Token is valid for 1 hour. Call Login again with a valid Partner Token to refresh, then update clients with the new sdp_suki_token. See Suki Token expired during a long session.
invalid_sdp_token is not a Partner Token Login failure. Fixing only partner_token does not help if later calls omit or keep a stale sdp_suki_token.

โ€‹
Next steps

Partner authentication - Token exchange, JWT claims, and auth troubleshooting Login - Exchange partner_id and partner_token for suki_token Ambient and Dictation error messages - Look up invalid_sdp_token and related ids Suki Token expired during a long session - Refresh after the 1 hour lifetime Wrong staging vs production endpoints - Align hosts, tokens, and SDK environment
Last modified on September 29, 2026