Your backend must support OAuth 2.0 token exchange to obtain Spotnana tokens on behalf of your users. This page explains the backend setup process:
Spotnana will provide you with a unique client_id and client_secret which you'll use to request an access token every time a user logs in to the platform. Store the client secret securely and never expose it in your codebase.
During the setup, you must provide a JWKS endpoint and a sample JSON Web token (JWT) payload which Spotnana will use to verify the identity of the logged-in user during token exchange.
You must host a publicly accessible HTTPS endpoint that exposes your RSA public keys in a standard JSON Web Key (JWKS) format (i.e., the RFC 7517 format). When a user logs in and your backend system submits a JSON Web Token (JWT) during token exchange, Spotnana fetches the public key from this endpoint to validate the token's signature.
Your JWKS endpoint must meet the following requirements:
- It must not require authentication.
- It must include a
kid(Key ID) for each key. Thiskidmust match thekidin the JWT header so Spotnana can authenticate the request.
You must also provide Spotnana with a decoded sample of the JSON Web Token (JWT) which your system will generate. We the user's email address in the payload to map the user in the Spotnana platform.
A JWT has three Base64URL-encoded parts separated by dots: <header>.<payload>.<signature>. The signature is computed using the encoded header and the payload.
Here's an example of an encoded JWT:
eyJraWQiOiJteS1rZXktaWQtMSIsImFsZyI6IlJTMjU2In0.eyJlbWFpbCI6ImpvaG4uZG9lQGN1c3RvbWVyLmNvbSIsImlzcyI6Imh0dHBzOi8vYXV0aC5jdXN0b21lci5jb20iLCJzdWIiOiIxM2Y3OTgyZC0xZjc4LTQ2ZTItYTg0My0zMjczNTY4ZmNlODkiLCJhdWQiOiJzcG90bmFuYSIsImlhdCI6MTcwOTA3ODQwMCwiZXhwIjoxNzA5MDgyMDAwfQ.<RS256 signature>The decoded header must use the RS256 algorithm and include a kid that matches a key in your JWKS endpoint:
{
"alg": "RS256",
"kid": "my-key-id-1"
}The decoded payload must include the user's email at the root level as shown below:
{
"email": "john.doe@customer.com",
"pid": "13f7982d-1f78-46e2-a843-3273568fce89",
"iss": "https://auth.customer.com",
"sub": "13f7982d-1f78-46e2-a843-3273568fce89",
"aud": "spotnana",
"iat": 1709078400,
"exp": 1709082000
}Notes:
- The email must be present in the decoded payload with the
userEmail) or if it's nested within a different field (e.g.,user.email) then contact your Spotnana representative to configure this custom mapping.- The email address must be the same as the one used to create the user's profile on the Spotnana platform.
- Only the RS256 (RSA with SHA-256) algorithm is supported for JWT signature generation and validation.
To obtain a Spotnana access token on behalf of the user, your system must send a POST request to the OAuth token generation endpoint.
Here's a sample API request schema:
curl -X POST "https://api-ext-sboxmeta.partners.spotnana.com/v2/auth/oauth2-token" \
-d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
-d "client_id=<SPOTNANA_CLIENT_ID>" \
-d "client_secret=<SPOTNANA_CLIENT_SECRET>" \
-d "subject_token=<SIGNED_JWT_WITH_USER_EMAIL>" \
-d "subject_token_type=urn:ietf:params:oauth:token-type:jwt" \
-d "scope=openid"Here's a sample response:
{
"access_token": "eyJraWQiOi...",
"refresh_token": "eyJjdHkiOi...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "openid"
}The table below explains the different parameters used in the OAuth token generation API request:
| Parameter | Required? | Description |
|---|---|---|
grant_type | Yes | Must contain the value: urn:ietf:params:oauth:grant-type:token-exchange. |
client_id | Yes | Your Spotnana client ID. |
client_secret | Yes | Your Spotnana client secret. |
subject_token | Yes | Your application's signed JWT containing the user's email. Spotnana validates the signature using your JWKS public key and extracts the email to identify the user. |
subject_token_type | Yes | Must contain the value: urn:ietf:params:oauth:token-type:jwt. |
scope | Yes | Must contain the value: openid. |