> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ripio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to generate a session token for the crypto widget.

### Before you begin

* **Credentials.** Contact Ripio to request your partner registration and obtain the `client_id` and `client_secret` that uniquely identify you as a Ripio customer. It is your responsibility to secure them.
* **A signing key for webhooks.** Issued alongside your credentials — see [Webhooks](/crypto-as-a-service/widget/webhooks).

<Note>
  This is the only widget endpoint you call directly, and it must be called from your **server**, never from the browser: `client_secret` should never reach the end user's device. Every other request — quotes, execution, portfolio, activity — is made by the widget itself on the user's behalf, so there is no other widget API for you to integrate against.
</Note>

### Generate a session token

Endpoint: `https://b2b-crypto-widget-api.sandbox.ripio.com/api/v1/auth`

Method: `POST` · Content-Type: `application/json`

| Field                  | Type                         | Description                                                                                                                                                |
| ---------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id`            | *string*                     | Identifies your account.                                                                                                                                   |
| `client_secret`        | *string*                     | Your account's secret. Never send this from the browser.                                                                                                   |
| `external_ref`         | *string*                     | A unique, unrepeatable identifier for the user in your own system. Used to correlate webhooks and to map the widget session back to your user.             |
| `requested_operations` | *array of string* (optional) | Narrow this session to a subset of `deposit`, `withdrawal`, `swap`, `yields`, `loan`, `buy`, `sell`. Omit it to grant everything your account has enabled. |

Request:

```bash theme={null}
curl \
  --location --request POST 'https://b2b-crypto-widget-api.sandbox.ripio.com/api/v1/auth' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "<client_id>",
    "client_secret": "<client_secret>",
    "external_ref": "<your-user-id>"
  }'
```

Response:

```json theme={null}
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

Pass this `token` to the widget — as the `token` attribute or the `_to` query parameter — to start the user's session. See [Embedding the widget](/crypto-as-a-service/widget/get-started/embedding).

<Warning>
  The token is a bearer credential for that one user's session. Treat it the same way you'd treat any other short-lived access token: pass it to the client over a secure channel and don't log it.
</Warning>

### Narrowing a session

```json theme={null}
{
  "client_id": "<client_id>",
  "client_secret": "<client_secret>",
  "external_ref": "<your-user-id>",
  "requested_operations": ["buy", "sell"]
}
```

This session can only buy and sell, regardless of what else your account has enabled — useful when you want a specific entry point of your app to expose a narrower widget than your account is capable of.

### Errors

| Cause                                  | What happens                                                                                               |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Invalid `client_id` or `client_secret` | `401`. The same generic error either way — Ripio doesn't distinguish "unknown client" from "wrong secret". |
| Too many requests for your `client_id` | `429`. The token endpoint is rate-limited per account regardless of the caller's IP.                       |

See [Troubleshooting](/crypto-as-a-service/widget/troubleshooting) for the full error contract used across the widget's endpoints.