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 and publishable keys

Odus has two types of API keys:

Type	Prefix	Where to use	Scope
Secret key	skey_	Server-side only	Configurable — can be scoped to specific actions
Publishable key	pk_	Client-side code, browsers	Limited — read-only, safe for public environments

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.

For publishable keys, see Publishable Key.

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 /secret-keys.

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/payments \
  -H "Authorization: Bearer skey_your_secret_key_here" \
  -H "Content-Type: application/json"

fetch example

const response = await fetch('https://api.odus.com/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.

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 /secret-keys/{id}/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.