# Authentication

All server-side ODUS API calls must include a secret key to prove identity. This guide shows you how to create a secret key, add it to your requests, and rotate it when needed.

## Prerequisites

* Access to the ODUS Dashboard with an admin or owner role.
* A server environment where you can safely store credentials.

## Secret keys

ODUS API keys are secret keys. A secret key starts with `skey_`, is used on your server only, and can be scoped to specific actions.

warning

Never include a secret key in client-side code, mobile apps, or public repositories. Anyone who obtains your secret key can make API calls on your behalf.

The Checkout SDK does not use an API key. Its `apiKey` option is still required, so pass `'pk_retired'`: see [Checkout configuration](https://docs.odus.com/docs/guides/checkout/drop-in/configuration.md#root-options).

## Create a secret key

1. In the ODUS Dashboard, go to **Developers > Access Keys**.
2. Under the **Secret Keys** section, click **Add secret key**.
3. Enter a note to help you identify this key later (for example, `production-server` or `billing-service`).
4. Select the permissions this key needs. Grant only the permissions your integration requires.
5. Click **Add**.
6. Copy the key value immediately. **It is shown only once.** After you leave this page, ODUS will only display a masked version of the key.

You can also create a secret key via the API: [`POST /v2/secret-keys`](https://docs.odus.com/docs/api/core/v2/secret-key-controller-create).

## Add the key to your requests

Include the secret key as a Bearer token in the `Authorization` header of every server-side API request.

curl example

```
curl https://api.odus.com/v2/payments \

  -H "Authorization: Bearer skey_your_secret_key_here" \

  -H "Content-Type: application/json"
```

fetch example

```
const response = await fetch('https://api.odus.com/v2/payments', {

  method: 'GET',

  headers: {

    Authorization: `Bearer ${process.env.ODUS_SECRET_KEY}`,

    'Content-Type': 'application/json',

  },

});
```

Store the key in an environment variable, not in source code.

Every v2 path starts with `/v2`. A request without the prefix reaches v1, which stops being served on 4 November 2026.

## Rotate a secret key

Rotation replaces an old key with a new one. You should rotate a key when:

* You suspect the key has been leaked or exposed.
* A team member with access to the key leaves your organization.
* Your security policy requires periodic rotation.

**To rotate a key:**

1. Create a new secret key following the steps above.
2. Update your application to use the new key.
3. Verify the new key works correctly in production.
4. Delete the old key: in the Dashboard, find the key in **Developers > Access Keys** and delete it. You can also use the API: [`POST /v2/secret-keys/{id}/delete`](https://docs.odus.com/docs/api/core/v2/secret-key-controller-delete).

important

Delete the old key only after your application is fully updated to use the new one. Deleting the old key immediately will break any requests that still use it.

A key cannot be switched off and on again: deleting it is the only way to revoke it. `POST /v2/secret-keys/{id}` changes a key's `note` and `permissions` only.