Authentication

Generating a token#

1. Sign in to your Ocean.io account
2. Navigate to Account Settings → API Tokens
3. Click Generate new token
4. Copy the token and store it securely — it will not be shown again

Note

Treat your API token like a password. Do not commit it to version control or expose it in client-side code.

Authenticating requests#

Include your token on every request using one of the following methods. Do not use both simultaneously — this will result in a 400 error.

Method 1 — Request header (recommended):

curl -X GET "https://api.ocean.io/v2/credits/balance" \
  -H "X-Api-Token: YOUR_API_TOKEN"

import requests

response = requests.get(
    'https://api.ocean.io/v2/credits/balance',
    headers={'X-Api-Token': 'YOUR_API_TOKEN'},
)

const response = await fetch('https://api.ocean.io/v2/credits/balance', {
  headers: { 'X-Api-Token': 'YOUR_API_TOKEN' },
});

Method 2 — Query parameter:

curl -X GET "https://api.ocean.io/v2/credits/balance?apiToken=YOUR_API_TOKEN"

import requests

response = requests.get(
    'https://api.ocean.io/v2/credits/balance',
    params={'apiToken': 'YOUR_API_TOKEN'},
)

const response = await fetch(
  'https://api.ocean.io/v2/credits/balance?apiToken=YOUR_API_TOKEN',
);

Headers don't appear in server logs or browser history — query parameters do.

Token errors#

Rotating tokens#

If you suspect a token has been compromised, revoke it immediately in Account Settings and generate a new one. Update all systems using the old token before revoking to avoid downtime.