> ## Documentation Index
> Fetch the complete documentation index at: https://yn-c9bb3266.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.          |

<Warning>
  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](https://dashboard.y.uno).
</Warning>

## 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

<Steps>
  <Step title="Open the Dashboard">
    Sign in to the [Yuno Dashboard](https://dashboard.y.uno) with your merchant account.
  </Step>

  <Step title="Navigate to API Keys">
    Go to **Developers**. You will see separate credentials for sandbox and production.
  </Step>

  <Step title="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](/getting-started/environments) for the base URL per environment.
  </Step>
</Steps>

## Example request

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

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
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.

<CardGroup cols={2}>
  <Card title="Sandbox" icon="flask">
    **Base URL**

    `https://api-sandbox.y.uno`

    **Credentials**

    Sandbox keys from the Dashboard. No real funds. Use the [Yuno Testing Gateway](/guides/testing/yuno-testing-gateway) and [test cards](/guides/testing/test-cards) to exercise flows.
  </Card>

  <Card title="Production" icon="globe">
    **Base URL**

    `https://api.y.uno`

    **Credentials**

    Production keys from the Dashboard. Real funds, real customers, real settlement.
  </Card>
</CardGroup>

See [Environments](/getting-started/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](/api-reference/customers/get-by-external-id) |
| Payment   | `merchant_order_id` (on the upstream checkout session) | [Get Payment by Merchant Order](/api-reference/payments/get-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](/core-concepts/idempotency) 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](https://dashboard.y.uno) for unexpected patterns.

## What next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/getting-started/quickstart-payments">
    Your first sandbox payment end to end.
  </Card>

  <Card title="Environments" icon="server" href="/getting-started/environments">
    Sandbox vs production and the go live checklist.
  </Card>

  <Card title="Avoiding duplicates" icon="rotate" href="/core-concepts/idempotency">
    Safe retries with unique business keys.
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/core-concepts/error-handling">
    The error envelope and which codes are safe to retry.
  </Card>
</CardGroup>