Authentication

The two headers every Yuno request needs, where to store them, and how to rotate them safely.

Every Yuno API call carries two authentication headers. Knowing what each one does, where to keep it, and when to rotate it is the difference between a secure integration and a liability.

The two required headers

Header	What it does	Where you use it
public-api-key	Identifies your account publicly.	Client SDK initialization and server calls.
private-secret-key	Authorizes server side operations.	Server only. Never in client code.

Never expose your private-secret-key in client code, mobile apps, browser bundles, or version control. Treat it like a database password. If it leaks, rotate it immediately from the Dashboard.

The account code

The Dashboard also exposes an account_id value for your account. This is not an HTTP header. It is a value you place inside request bodies on endpoints that take an account_id field, such as POST /v1/checkout/sessions and POST /v1/payments. The gateway derives the account scope internally from your authenticated key pair, then matches the account_id you sent in the body to confirm which account the call should run against.

If you maintain a single account, set account_id once in your client config. If you operate multiple accounts under one organization, branch on the merchant context to pick the right account_id per call.

Get your API keys

1. Open the Dashboard

   Sign in to the Yuno Dashboard with your merchant account.

2. Navigate to API Keys

   Go to Developers. You will see separate credentials for sandbox and production.

3. Copy the values

   Copy public-api-key and private-secret-key for the environment you need (sandbox for development, production for live traffic). Also copy the account_id value if your endpoints require an account_id body field. See Environments for the base URL per environment.

Example request

Every call sends the two headers together. This is the pattern you will repeat everywhere.

curl --request POST \
  --url https://api-sandbox.y.uno/v1/checkout/sessions \
  --header 'Content-Type: application/json' \
  --header 'public-api-key: YOUR_PUBLIC_API_KEY' \
  --header 'private-secret-key: YOUR_PRIVATE_SECRET_KEY' \
  --data '{
    "account_id": "YOUR_ACCOUNT_ID",
    "merchant_order_id": "order-001",
    "country": "BR",
    "amount": { "currency": "BRL", "value": 150.00 },
    "payment_description": "Premium subscription"
  }'

Sandbox and production credentials

Each environment has its own credentials. Sandbox keys against production (or the opposite) return an authentication error. Pick the right base URL and the matching key set for the environment you are calling.

Sandbox

Base URL

https://api-sandbox.y.uno

Credentials

Sandbox keys from the Dashboard. No real funds. Use the Yuno Testing Gateway and test cards to exercise flows.

Production

Base URL

https://api.y.uno

Credentials

Production keys from the Dashboard. Real funds, real customers, real settlement.

See Environments for the full sandbox vs production comparison and the go live checklist.

Safe retries

Yuno does not currently honor a generic X-Idempotency-Key header on most write endpoints. The dedupe pattern is a unique business key that you control and can look up later.

Resource	Set this field	Look up with
Customer	merchant_customer_id	Retrieve Customer by External ID
Payment	merchant_order_id (on the upstream checkout session)	Get Payment by Merchant Order
Recipient	merchant_recipient_id	Recipient lookup endpoint

The one exception today is POST /v1/subscriptions, which accepts an X-Idempotency-Key header with permanent dedupe per account. See Avoiding duplicates for the full pattern.

Security

1. Store keys in environment variables or a secret manager. Never commit them to git, hard code them, or log them.
2. Use different keys per environment (sandbox, staging, production) and per service where possible.
3. Rotate keys periodically from the Dashboard. Rotate immediately if a key is exposed.
4. Restrict private-secret-key to server code, CI secrets, and infrastructure vaults. The public key is the only one that may live on the client.
5. Monitor API usage in the Dashboard for unexpected patterns.

What next

Quickstart

Your first sandbox payment end to end.

Environments

Sandbox vs production and the go live checklist.

Avoiding duplicates

Safe retries with unique business keys.

Error handling

The error envelope and which codes are safe to retry.