Authentication

Your servers authenticate with an API key: a key and secret pair sent as X-Api-Key and X-Api-Secret headers on every request. There’s no login call, no token to refresh, and keys don’t expire.

Login tokens have been discontinued. The legacy Account ID and App Secret, POST /auth/login, GET /auth/refresh-token and Authorization: Bearer tokens no longer work for API requests. A request from your servers with a bearer token returns 403. Use an API key. See Move from login tokens to API keys.

You are building	Use
A backend, job or script that calls Yativo	API key (`X-Api-Key` + `X-Api-Secret`)
People signing in to the dashboard	Email code or passkey at app.yativo.com

Environments

Environment	Base URL
Production	`https://api.yativo.com/api/v1`
Sandbox	`https://smtp.yativo.com/api/v1`

Sandbox and production have separate keys. No real funds move in sandbox.

Create an API key

API access is available once your business KYC is approved.

Open API Keys

Generate a key

Click Generate key. Enter a Label (for example “Production backend”) and the Allowed IPs of the servers that will use the key. See IP whitelisting.

Save the secret

Copy the API secret and store it in a secrets manager. It’s shown only once and can’t be recovered.

Value	Header	Format
API key	`X-Api-Key`	`yativo_pk_...`
API secret	`X-Api-Secret`	`yativo_sk_...`

Authenticate requests

Send both headers on every request. Don’t send an Authorization header with them.

curl 'https://api.yativo.com/api/v1/wallet/balance' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Accept: application/json'

const yativo = (path, options = {}) =>
  fetch(`https://api.yativo.com/api/v1${path}`, {
    ...options,
    headers: {
      'X-Api-Key': process.env.YATIVO_API_KEY,
      'X-Api-Secret': process.env.YATIVO_API_SECRET,
      Accept: 'application/json',
      ...options.headers,
    },
  });

const res = await yativo('/wallet/balance');
const { data } = await res.json();

import os, requests

session = requests.Session()
session.headers.update({
    "X-Api-Key": os.environ["YATIVO_API_KEY"],
    "X-Api-Secret": os.environ["YATIVO_API_SECRET"],
    "Accept": "application/json",
})

data = session.get("https://api.yativo.com/api/v1/wallet/balance").json()["data"]

$response = Http::baseUrl('https://api.yativo.com/api/v1')
    ->withHeaders([
        'X-Api-Key'    => env('YATIVO_API_KEY'),
        'X-Api-Secret' => env('YATIVO_API_SECRET'),
    ])
    ->acceptJson()
    ->get('/wallet/balance');

Requests made with a key act on your business account. Some endpoints can’t be called with a key and return 403 This endpoint cannot be used with an API key. Sign in to the Yativo dashboard instead. Do these in the dashboard instead:

Passkeys, two-factor authentication and PIN changes
Deleting the account

API keys and IP whitelists can only be managed in the dashboard. Requests from anywhere else, including with an API key, return 403 IP whitelists and API keys can only be managed from the Yativo dashboard.

Check your setup

Call GET /ip-whitelist/check from each server that uses the key. It confirms the key works and whether that server’s IP is allowed.

curl 'https://api.yativo.com/api/v1/ip-whitelist/check' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

If your integration still calls POST /auth/login, it no longer works. Request and response bodies don’t change. Only the authentication headers do.

	Login tokens (discontinued)	API keys
Authenticate	`POST /auth/login`, then `Authorization: Bearer <token>`	`X-Api-Key` + `X-Api-Secret` on every request
Token refresh	`GET /auth/refresh-token`	Not needed
Expiry	Tokens expire	Never. Works until revoked
Revoke access	Generate a new App Secret	Revoke one key
Allowed IPs	Any	Only the IPs on the key
Works for API requests	No	Yes

Find your server IPs

Run curl https://checkip.amazonaws.com on every server that calls Yativo.

Create a key per system

Create one API key per system with its allowed IPs, so you can revoke one without affecting the others.

Update your client

Remove the /auth/login call, token caching and refresh, and the Authorization header. Add X-Api-Key and X-Api-Secret to every request. If you send both, the bearer token is ignored.

Test and go live

Test in sandbox, run GET /ip-whitelist/check from each production server, then deploy. IP whitelists have been enforced since 14 October 2026, so a key without your server’s IP is refused.

Remove the old secret

Delete the legacy Account ID and App Secret from your configuration.

Idempotency

Send an Idempotency-Key header on every POST, PUT, PATCH and DELETE request. It makes retries safe: a repeated request returns the original response and doesn’t run again.

Idempotency-Key: <unique-string-per-request>

Use a UUID or another value you generate once per operation, and reuse it only when retrying that operation.

Yativo keeps the original response for 60 minutes. A retry with the same key and body in that time gets the same response, including errors below 500. A 5xx response isn’t kept, so you can retry it with the same key.
Reusing a key with a different body returns 409 with Idempotency key reuse detected with a different request payload.
Sending a retry while the first request is still running returns 409 with A matching request is already being processed. Please wait a moment and refresh.
If you leave the header out, Yativo treats an identical request to the same endpoint within 60 minutes as a retry, and returns the first response. To send two identical operations on purpose, such as two equal payouts, give each its own key.

curl -X POST 'https://api.yativo.com/api/v1/wallet/payout' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

Errors

HTTP	`data.error`	Fix
401	`Both X-Api-Key and X-Api-Secret headers are required.`	Send both headers.
401	`Invalid or revoked API credentials.`	Check the key and secret belong to the same key and environment, or create a new key.
403	`This API key has no whitelisted IP addresses. Add at least one allowed IP before using it.`	Add your server’s IPs to the key in the dashboard.
403	`This IP address is not allowed to use this API key.`	Add your server’s IP to the key. See IP whitelisting.
403	`Bearer tokens are only accepted from the Yativo dashboard. ...`	Login tokens are discontinued. Send `X-Api-Key` and `X-Api-Secret` instead.
403	`This endpoint cannot be used with an API key. ...`	Make the change in the dashboard.
403	`IP whitelists and API keys can only be managed from the Yativo dashboard.`	Manage keys and IPs in Developers → API Keys.
409	`Idempotency key reuse detected with a different request payload.`	Use a new `Idempotency-Key` for a new operation.

Security best practices

Store the key and secret in a secrets manager or environment variables. Never commit them or log them.
Only call the API from your backend. Never put a key in a browser or mobile app.
Use a separate key for each system and environment.
Revoke a key straight away if you think it has leaked, then create a new one.
Turn on two-factor authentication and passkeys for everyone who signs in to the dashboard.

Get Started

Payments

Wallets

Customers & Compliance

Transactions

Products

Developer Tools

SDKs

Regional Guides

Authentication

Environments

Create an API key

Authenticate requests

Check your setup

Idempotency

Errors

Security best practices

​Environments

​Create an API key

​Authenticate requests

​Check your setup

​Move from login tokens to API keys

​Idempotency

​Errors

​Security best practices

Environments

Create an API key

Authenticate requests

Check your setup

Move from login tokens to API keys

Idempotency

Errors

Security best practices