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.
Your users’ identity data. Every POST /auth carries the user’s KYC data. Check which fields your country needs before you start — see User verification (KYC).
Webhook keys, if you receive webhooks. An exchange of Ed25519 public keys: Ripio gives you its public key to verify the requests it sends, and you give Ripio yours to verify your responses — 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.

How a session starts

You never handle the user’s session token. Your server asks Ripio for a session code, you hand that code to the widget, and the widget exchanges it for the session on its own as soon as it loads.

Your server calls POST /auth and receives a session_code.
You pass the code to the widget — as the code property when embedding it, or in the URL fragment for a WebView.
The widget redeems the code, removes it from the URL and the page, and starts the user’s session.

A session code works once and expires after 2 minutes. That is what makes it safe to pass through a URL or a page attribute: by the time it could show up in a log, a browser history entry or a support screenshot, the widget has already used it.

Generate a session code

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.
`kyc_submission`	object	The user’s identity data, keyed by the fields your country requires. Ripio uses it to register and verify the user, and ignores it once they can operate. See User verification (KYC).
`email`	string (optional)	The user’s email. Required unless your account approves KYC automatically.
`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.
`style`	string (optional)	The slug of one of your account’s styles. The widget renders this session with it. Omit it to use your default style.

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>",
    "email": "[email protected]",
    "kyc_submission": {
      "country": "AR",
      "first_name": "Ana",
      "last_name": "Diaz",
      "cuit": "20123456786"
    }
  }'

The kyc_submission above is shortened: send every field your country requires, as listed in User verification (KYC). Response:

{
  "session_code": "k7Qe2Vn9Hc4yR1bT0sWmZpL8xA3dFgJ6uEoNiKqYtUw",
  "expires_in": 120
}

Field	Description
`session_code`	Pass it to the widget to start the user’s session. See Embedding the widget.
`expires_in`	Seconds the code stays redeemable.

Request the code right before you open the widget — not when the user logs into your app, and never cached for later. It expires in 2 minutes and works only once: a code that was already used, or that you reuse for a second widget, starts no session. Mint a new one for every time the widget is opened.

Once redeemed, the session lasts one hour from the moment you called POST /auth. When it ends, the widget tells you so you can hand it a fresh code without reloading your page — see Session lifecycle.

Narrowing a session

{
  "client_id": "<client_id>",
  "client_secret": "<client_secret>",
  "external_ref": "<your-user-id>",
  "kyc_submission": {...},
  "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.

Picking a style

If your account has more than one style, send the one this entry point uses:

{
  "client_id": "<client_id>",
  "client_secret": "<client_secret>",
  "external_ref": "<your-user-id>",
  "kyc_submission": {...},
  "style": "mobile-app"
}

The user, balances and limits are the same whatever style you pick: only the widget’s look changes.

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 endpoint is rate-limited per account regardless of the caller’s IP.
`kyc_submission` is missing or isn’t an object	`400`, code `20000`. No session is started.
Ripio rejected the user’s data — a required field is missing or a value is invalid	`400`, code `20013`, with `detail` naming each field to fix. No session is started. See When Ripio rejects the data.
`style` isn’t one of your account’s styles	`400`, code `20014`. No session is started.

See Troubleshooting for the full error contract used across the widget’s endpoints.

Overview

Crypto Widget

API Integration

Before you begin

How a session starts

Generate a session code

Narrowing a session

Picking a style

Errors

​Before you begin

​How a session starts

​Generate a session code

​Narrowing a session

​Picking a style

​Errors

Before you begin

How a session starts

Generate a session code

Narrowing a session

Picking a style

Errors