Authentication

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.

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.

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:

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:

{
  "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.

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.

Narrowing a session

{
  "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 for the full error contract used across the widget’s endpoints.

Overview

Widget

API Reference

Before you begin

Generate a session token

Narrowing a session

Errors

​Before you begin

​Generate a session token

​Narrowing a session

​Errors

Before you begin

Generate a session token

Narrowing a session

Errors