> ## 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 an authentication token for the On/Off Ramp Widget.

### Before you begin

* **Credentials.** Contact Ripio support to request your partner registration and obtain the `client_id` and `client_secret` that univocally identify you as a Ripio customer. It is your responsibility to secure them.
* **A redirect URL.** Ripio needs a publicly reachable URL to send the user back to once the operation is confirmed. You give it to Ripio during onboarding and it is configured on your account — see [Returning to your app](/ramps-api/widget/get-started/returning-to-your-app).
* **Whether your account requires a wallet address.** If it does, the `username` below must carry a third segment. See [Errors](#errors).

<Note>
  This is the only widget endpoint you call. Every other request — quotes, orders, verification, history, refunds — is made by the widget itself on the user's behalf, so there is no other widget API for you to integrate against. What your backend observes instead are the [Ramps webhooks](/ramps-api/webhooks/introduction) you already receive.
</Note>

### Generate authentication token

This service provides an access JWT token for the user to use the On Ramp Widget.

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

> **Sandbox:**: `https://b2b-widget-onramp-api.sandbox.ripio.com/api/v1/auth`

Method: `POST`

Parameters:

| Parameter  | Type     | Description                                                                                              |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `username` | *string* | The username is composed of a concatenation of `client_id` + “`:`" + `external_ref` + “`:`" + `address`. |
| `password` | *string* | The password is the `client_secret`                                                                      |

*Disclaimer*:

* `external_ref`: **UUID** v4 that represents the user logged into your system. It must be a unique and unrepeatable identifier of a user of your system ([Read more about UUID](https://developer.mozilla.org/en-US/docs/Glossary/UUID) and try using [generator](https://www.uuidgenerator.net/)). This value is then used in the request for approval of a purchase transaction or when reporting the result of a transaction. (see [Webhooks](/ramps-api/webhooks/introduction)). In the documentation we refer to this value as external\_ref. It is validated as a UUID, so a non-UUID value is rejected.
* `address`: A string that represents the blockchain address or wallet identifier for the user. For off-ramp operations, use the same address as used in on-ramp. Whether it is mandatory depends on your partner configuration — if your account requires it, omitting it returns a 422 (see [Errors](#errors)). If it is not required for your account, you can send a two-part `username` (`client_id:external_ref`).

Request:

```bash theme={null}
curl \
--location --request POST 'https://b2b-widget-onramp-api.ripio.com/api/v1/auth' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=<client_id>:<external_ref>:<address>' \
--data-urlencode 'password=<client_secret>'
```

Example:

```bash theme={null}
curl \
--location --request POST 'https://b2b-widget-onramp-api.ripio.com/api/v1/auth' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=<client_id>:123e4567-e89b-42d3-a456-426614174000:0x05946b0d5E413e45069BeC923004F9A3c8F70C2C' \
--data-urlencode 'password=<client_secret>'
```

Response:

```json theme={null}
{
    "succeed": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uIjoiMThhYjZkNmM4ZDk4NWE5Y2M4N2IwMTcyN2ExMWYwOTQ4YzJmNGUxYzQ0ODEzZTZhNDU0MzcxYTg1NzY3YjE5OSIsImV4cCI6MTcwODI5ODMzM30.4aRUEXLkUs3jf-DYMcH8claUuDKfc8qbTjW6JzpBTjI",
    "token_type": "bearer"
}
```

<Note>
  This endpoint returns the token under a `token` key, not nested under `data` like most other widget API responses.
</Note>

### Errors

Validation failures return **HTTP 422** with a flat body — just a `detail` string field:

```json theme={null}
{
    "detail": "address is required for this partner"
}
```

| `detail`                                                                              | Cause                                                                                                                                                                |
| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `address is required for this partner`                                                | Your account requires the wallet address and the `username` had no third segment. Note an explicitly empty third part (`client_id:external_ref:`) counts as missing. |
| `username must be in format client_id:external_ref or client_id:external_ref:address` | The `username` had fewer than 2 or more than 3 colon-separated segments.                                                                                             |
| `missing external_ref`                                                                | The second segment of the `username` was empty.                                                                                                                      |
| `The external_ref is not a UUID`                                                      | The `external_ref` was present but not a valid UUID.                                                                                                                 |