Manage API keys

An API key lets a script call the Coritan API as you, without your password or a second factor. The API keys tab of Settings creates keys, each with a label, a set of permissions and an optional list of addresses it may be used from. You see each key once, when you create it.

A key works until you revoke it. It is the way to give a script, a CI job or a cron job access to your account. Make your first API request walks through a script that uses one.

Other Coritan credentials work with their own APIs:

• An organization API key calls the Commerce API for one organization.
• An SMTP Relay API key sends mail with the SMTP Relay API.

• Sign in to the dashboard.

1. In the sidebar, select Settings, then the API keys tab.
2. Select Create API key…. The Create an API key page opens at /dashboard/settings/api-keys/new.
3. Under Name, type a Label, such as CI deploys, so you can tell the key apart from your others. It can be up to 100 characters.
4. Under Permissions, choose a Preset: Read only switches on every Read switch, Full access switches on all twenty, and Custom keeps the switches as they are. Then switch Read or Write on or off for each area the key needs: Services, App Deployment, Cloud Compute, DNS, Floating IPs, Mail Services, Storage, Domain Management and Edge Proxy, Billing and Support. Changing a single switch moves the preset to Custom. A new key starts on Read only. The What this key can do card beside the form says in words what the switches allow, and What a key can do explains how Coritan reads them.
5. Optionally, under Where it can be used, list the addresses the key may be used from in IP allow-list: one IPv4 or IPv6 address or CIDR range per line, such as 203.0.113.10 or 2001:db8::/32. Leave it empty to allow any address.
6. Select Create API key. A key with every switch off is refused with Choose at least one permission., and the page keeps everything you entered.
7. The page now shows Copy this key now in place of the form. Copy the key. It starts with ct_, and Coritan shows it only this once. Keep it where only your script can read it, such as a secret in your CI system. Select I have saved it to go back to the API keys tab, where the key is now listed. If you try to leave the page before that, the dashboard asks first.

Coritan emails you when a key is created.

Send the key in the Authorization header of each request, as Authorization: Bearer <key>:

curl -s "https://api.coritan.com/api/v1/services/?limit=5" \
  -H "Authorization: Bearer $CORITAN_TOKEN"

The request acts as you, on your own account. The examples in these docs send $CORITAN_TOKEN, so a script can keep its key in that variable and run them as they are, apart from the routes that no key can reach.

• A key with at least one Write permission can make every change you can, apart from what no key can do.
• A key with only Read permissions can only read: GET and HEAD requests, and POST /api/v1/checkout/quote, which prices an order without placing it. Any other request answers 403 with "code": "api_key_read_only".
• A key with no permissions cannot make any request. Each one answers 403 with "code": "api_key_no_permissions".

Coritan checks the level, not the area. A key with Write ticked for DNS alone can also change your deployments and your billing. Give each script its own key, and revoke a key when its script no longer needs it.

A key cannot reach the routes below, whatever its permissions. Each one answers 403 with "code": "api_key_route_refused" and a sentence that names what a key cannot do. Use the dashboard for them, or a script that signs in, as Make your first API request shows.

A key cannot work in another account you joined either. A request that sends one with the X-Coritan-Account header answers 403 with "code": "api_key_act_for_refused".

A WebSocket, such as a server's live console, takes an access token, not a key.

When a key has an IP allow-list, a request from any other address answers 403 with "code": "api_key_address_refused". The message names the address the request came from, as Coritan saw it. Behind a proxy or a NAT gateway, that is the gateway's public address. You cannot change a key's allow-list, so create a new key with the right addresses and revoke the old one.

1. On the API keys tab, select the bin icon at the end of the key's row.
2. Type the key's label to confirm. A key with no label asks for the word revoke.
3. Select Revoke key.

A script that sends a revoked key gets 401 Invalid or expired token within a few seconds.

Changing your password or signing out your sessions leaves your keys working. If a key may have leaked, revoke it. Closing your account switches off every key, and while an account is suspended, its keys answer 403 Account is suspended or closed.

The list shows each key with its label and creation date under Key, then Permissions, Allowed from (Any address when it has no allow-list) and Last used. Last used shows when the key last made a request, or Never. Coritan updates it at most once a minute, and a request that was refused does not count.

Enter a label so you can tell this key apart from your others.

The Label is empty. Type one.

Line 2: enter an IP address or a CIDR range.

A line in IP allow-list is not an address or a range. The message names the line. Fix it or delete it.

401 Invalid or expired token with a ct_ key

The key is wrong, or it was revoked. Check that the script sends the whole key after Bearer, or create a new key.

403 Account is suspended or closed

The account the key belongs to cannot make requests. Contact support.

403 with "code": "api_key_read_only"

The key has only Read permissions. Create a key with a Write permission for the script.

403 with "code": "api_key_route_refused"

No key can reach that route. What no key can do lists them.

403 with "code": "api_key_act_for_refused"

The request sent the X-Coritan-Account header. A key works only on its own account, so send it without the header.

403 with "code": "api_key_address_refused"

The request came from an address that is not on the key's IP allow-list. The message names the address. Create a key whose allow-list includes it.

403 with "code": "api_key_no_permissions"

The key has no permissions. Create a key with the permissions the script needs.

You lost a key

Coritan cannot show it again. Revoke it and create another.

• Make your first API request
• Authentication
• Share your account with a team
• Create organization API keys

These endpoints take your access token. A key cannot create, list or revoke keys.

Create a key with POST /auth/me/api-keys. label is required (1–100 characters). permissions is an optional list of area:read and area:write entries, where the area is one of services, servers, vps, dns, ips, mail, storage, websites, billing and support. ip_whitelist is an optional list of up to 100 addresses and CIDR ranges. Any other entry answers 422 with a message that names it, such as "dns:admin" is not a permission. Coritan saves each permission once and each address in its standard form, such as 198.51.100.0/24 for 198.51.100.7/24.

curl -X POST https://api.coritan.com/api/v1/auth/me/api-keys \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "CI deploys", "permissions": ["services:read"], "ip_whitelist": ["203.0.113.10"]}'

{
  "id": 17,
  "label": "CI deploys",
  "permissions": ["services:read"],
  "ip_whitelist": ["203.0.113.10"],
  "is_active": true,
  "last_used_at": null,
  "created_at": "2026-09-16T10:02:11",
  "raw_key": "ct_..."
}

raw_key is in this answer only. List your keys, newest first, with GET /auth/me/api-keys. It takes limit (default 200, at most 500) and returns the same fields without raw_key.

Revoke a key with DELETE /auth/me/api-keys/{key_id}. It answers {"message": "API key revoked"}, or 404 API key not found for a key that is not yours or no longer exists.