# Backend setup

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:

## Get client credentials from Spotnana

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.

## Provide a JSON Web Key (JWKS) endpoint

During the setup, you must provide a [JWKS](https://datatracker.ietf.org/doc/html/rfc7517) endpoint and a sample [JSON Web token](https://en.wikipedia.org/wiki/JSON_Web_Token) (JWT) payload which Spotnana will use
to verify the identity of the logged-in user during token exchange.

### A JWKS endpoint URL

You must host a publicly accessible HTTPS endpoint that exposes your [RSA public keys](https://en.wikipedia.org/wiki/RSA_cryptosystem) in a
standard JSON Web Key (JWKS) format (i.e., the [RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517) 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. This `kid` must match the `kid` in the JWT header so Spotnana can authenticate the request.


### Sample JWT payload

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:


```json

eyJraWQiOiJteS1rZXktaWQtMSIsImFsZyI6IlJTMjU2In0.eyJlbWFpbCI6ImpvaG4uZG9lQGN1c3RvbWVyLmNvbSIsImlzcyI6Imh0dHBzOi8vYXV0aC5jdXN0b21lci5jb20iLCJzdWIiOiIxM2Y3OTgyZC0xZjc4LTQ2ZTItYTg0My0zMjczNTY4ZmNlODkiLCJhdWQiOiJzcG90bmFuYSIsImlhdCI6MTcwOTA3ODQwMCwiZXhwIjoxNzA5MDgyMDAwfQ.<RS256 signature>
```

The decoded header must use the RS256 algorithm and include a `kid` that matches a key in your JWKS endpoint:


```json
{
  "alg": "RS256",
  "kid": "my-key-id-1"
}
```

The decoded payload must include the user's email at the root level as shown below:


```json
{
  "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 `email` field as shown in the above sample. If the name of the parameter is different (e.g., `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](https://en.wikipedia.org/wiki/JSON_Web_Token) (RSA with SHA-256) algorithm is supported for JWT signature generation and validation.



## Token exchange request

To obtain a Spotnana access token on behalf of the user, your system must send a POST request to the [OAuth token generation](/docs/openapi/authapi/authentication/fetchoauth2token) endpoint.

Here's a sample API request schema:


```shell
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:


```json
{
  "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](/docs/openapi/authapi/authentication/fetchoauth2token) 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`. |