Get started

Authentication and API keys

Every request to the API carries an API key in the Authorization header. This page shows how to send it, and how to create, store and revoke keys.

Send your key

Put the key in the Authorization header of each request, after the word Bearer:

Authorization: Bearer sk-shfr-...

The OpenAI libraries send this header for you: give them the key as api_key (Python) or apiKey (Node.js). These three requests do the same thing:

curl https://acacus.ly/v1/chat/completions \
  -H "Authorization: Bearer $ACACUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "Say hello."}],
    "thinking": {"type": "disabled"}
  }'

• POST /v1/chat/completions and GET /v1/usage need a key. GET /v1/models and GET /v1/models/{id} work without one.
• Bearer can be written in any letter case. One or more spaces separate it from the key.
• Only this header is read. A key sent in another header, such as x-api-key, is not seen, and the request gets 401 MISSING_API_KEY.
• Send the key as it is, with no quotes around it and no spaces in it.

thinking in the samples turns off DeepSeek's thinking step, which a paid request would otherwise pay for. See Reasoning.

Check a key

GET /v1/usage needs a key, but it costs nothing and doesn't count toward your rate limit, so it is a quick way to check one. A working key gets your token counts:

curl https://acacus.ly/v1/usage \
  -H "Authorization: Bearer $ACACUS_API_KEY"

{
  "todayTokens": 72,
  "totalTokens": 72
}

todayTokens counts the prompt and output tokens of your requests since 00:00 UTC, and totalTokens all of them. Both include your use of the Acacus chat. A missing or wrong key gets 401 (see Errors below).

Create a key

1. Sign in and open API keys in the console.
2. Click Create key. Type a name if you like, up to 64 characters, such as the app or server that will use the key. Without one, the console gives the key a default name (“Untitled key” in the English console).
3. Click Create key again. The key appears once, under Save your API key. Click Copy key, store the key (see below), then click Done.

A key is sk-shfr- followed by 40 characters (digits and the letters a to f), 48 characters in all. We keep only a hash of the key (SHA-256) and its first 12 characters, so nobody can show you the key again. If you lose a key, create a new one and revoke the old one.

The list shows each key's name, its first 12 characters (like sk-shfr-2729•••••), when it was created and when it was last used (“Never” until its first request).

Keep your keys safe

• Use keys on your server only. The API sends no CORS headers, so browsers block calls from web pages, and a key inside a web page or a mobile app can be read by anyone who uses it.
• Keep the key in an environment variable or your platform's secret store. Don't put it in your code or in a git repository.
• Create one key per app or environment, for example production, staging and your laptop, and name each key after it. Then you can revoke one key without stopping the others.
• Usage is recorded per account, not per key: the Usage page doesn't show which key sent a request.

Revoke a key

On API keys, click Revoke next to the key, then Revoke key. This can't be undone, and the key leaves the list.

A revoked key stops working at once: the API looks the key up on every request, so the next request with it gets 401 INVALID_API_KEY. A reply that is already streaming when you revoke the key still finishes.

If a key has leaked, revoke it first. Then create a new key and put it where the old one was.

What keys share

All the keys of an account share:

• one API balance: every request is billed to it;
• one free daily allowance;
• one rate limit: 30 requests a minute and 3 requests at a time.

Your own use of the Acacus chat is never charged to the API balance. It counts toward the same limits, and without a chat plan its daily free allowance uses the same daily allowance. See Billing and the free tier and Rate limits and other limits.

Keys don't expire and can't be renamed. They have no scopes and no limits of their own: every key can use the whole API, up to your balance.

Suspended accounts

If an account is suspended, every request made with one of its keys gets 403 ACCOUNT_SUSPENDED. Inside error, a suspension object says more:

A suspended account can't create keys, and neither can an account that is scheduled for deletion. To ask about a suspension, write to us on WhatsApp at +218 94 380 1609.

Errors

This is the reply to a key that doesn't exist:

{
  "error": {
    "message": "Invalid API key: it is unknown or was revoked. Keys are managed at https://acacus.ly/platform/api-keys",
    "type": "authentication_error",
    "code": "INVALID_API_KEY",
    "param": null
  }
}

Retrying doesn't help with these errors: fix the key or the header first. The error format and the other codes are in Errors.

Next steps