API keys

How to let your own scripts and tools read your bots and signals, and manage bots, without logging in: creating a key, what each scope allows, the exact request, the limits and how to keep the key safe.

A webhook is Okkana calling your server. An API key is the other direction: your script, automation or program calls Okkana, proves who it is with the key, and gets or changes your data without a login.

A key reaches two things in your account: your bots and your signals. It can list and read them and, if you allow it, create, edit, pause, duplicate and delete bots. That covers exporting signals to a spreadsheet, pausing bots from an n8n flow or letting an AI agent draft a bot.

It does not reach market data, your profile, your webhook or the live feed, and it can't create other keys. Okkana still never places an order.

In your profile, under API keys, give the key a name that says where it will run, such as the tool's name, and choose its access: Read, which lists and reads bots and signals, or Read and write, which also creates, edits and deletes bots.

A key starts with okk_ followed by 43 letters and digits. Okkana shows it once, when you create it. Only a one-way fingerprint is stored, so a lost key can't be recovered: revoke it and create another.

You can have up to 10 active keys. Use one per tool, so you can revoke one without stopping the others.

A key carries scopes, and each route asks for one. bots:read lists bots and reads one with its statistics. signals:read lists your signals, all of them or one bot's, and reads one with its conditions, performance and MFE/MAE. bots:write creates, replaces, pauses or activates, duplicates and deletes bots.

Scopes don't imply each other: a key with only bots:write can't list bots. The two profile presets are Read, with bots:read and signals:read, and Read and write, with all three.

A key whose scopes don't cover a route gets 403. So does any key on a route that isn't open to keys: markets, your profile, the webhook, alerts, the operations journal, the live feed and key management.

The catalog of metrics, templates and markets you build a rule from is public and needs no key.

Send the key in the Authorization header as Bearer okk_…, over HTTPS, on every request. Keep the key and the API address in environment variables.

Bodies and answers are JSON with camelCase names. Prices and quantities are decimal strings and times are UTC. Lists answer with items, nextCursor and asOf: send nextCursor back as cursor to read the next page, and limit to set the page size. Signals take botId to list one bot's signals.

Creating or replacing a bot goes through the same validation as the bot builder, and a rejected body answers with the fields that failed.

Each key has its own budget in a window of one minute, counted apart for reads (GET) and writes (everything else): 120 reads and 30 writes by default. Every answer from a route open to keys carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, the Unix time the window ends.

Over the budget the answer is 429 with a Retry-After in seconds: wait that long. A 401 means the key isn't valid: mistyped, revoked, expired or from a deleted account. A 403 means the key is valid but its scopes or the route don't allow the request.

Errors share one shape, with a code, a message and a request id to quote if you need help.

The key list in your profile shows each key's name, its first characters, scopes, creation date and last use, updated at most once a minute. A key you don't recognize, or that was used when you didn't expect, is a reason to revoke it.

Revoking works at once: the next request with that key answers 401.

The key belongs on the server that makes the requests, in an environment variable or a credential store such as your automation tool's. Never put it in a web page, front-end code, an app you distribute, a git repository or a screenshot: anyone who has it can do what its scopes allow. Prefer Read when the tool only reads.

A bot created through a key is an ordinary bot: it shows up in the app, counts toward your bot limit, fires signals, and its signals and statistics are the same as any other.

Okkana records which key created or edited a bot's definition, on that version of the bot. Pausing, activating and deleting are not versions, so nothing is added to the bot's history for them.

If a key is revoked later, the bots it made stay.