Skip to main content
View as Markdown
Version: v2

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.

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.

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