Keys

What a key is

A key looks like osk_ followed by an id and a secret. You send it as Authorization: Bearer osk_…. It is meant for a server, and it has its own spend caps and its own list of allowed models.

Create a key

1. Open API keys in the console and choose Create key.
2. Give it a name, and optionally an expiry, spend caps and a list of allowed models.
3. Copy the key when it is shown. It is shown once, with a ready-to-run example. Opsis keeps only a keyed hash of the secret, so it can never show it again.

An account can have 50 active keys, and needs a verified email before it can create one. Keys are made in the console only: no endpoint lets a key create or change keys.

Expiry

A key may expire in 7 days, 30 days, 90 days, 1 year, on a date you choose, or never. Never is the default, and the console recommends an expiry. You can move the date earlier or later while the key is active. After expiry the key stops working and stays in the list as expired; it cannot be revived.

Every response made with a key that expires within 14 days carries the header Opsis-Key-Expires-At, so your own monitoring can see it. A request with an expired key gets 401 invalid_api_key, and the message says when it expired.

Replace a key

A key's secret never changes. To replace a key, make a new one and retire the old one. The order that avoids downtime:

1. Create the new key with the same caps and allowed models.
2. Deploy it to the service that uses it.
3. Check in the key list that the old key's last used time has stopped moving.
4. Revoke the old key.

Between steps 1 and 4 both keys work. Three things change: the key's id, its spend counters (they start at zero), and the scope of idempotency, which is the key. Any key of the account can read any of the account's tasks, so work in flight can be read with the new key.

Revoke a key

Choose Revoke in the console and confirm by typing the key's name. It takes effect at once and cannot be undone. Tasks already accepted keep running and stay charged: revoking does not cancel work. The key stays in the list as revoked.

Spend caps

A cap refuses new tasks once a key has spent that much. There are three, all optional: daily (one UTC day, reset at 00:00 UTC), monthly (one UTC calendar month) and lifetime (never reset). What counts is the task's price at create. A refund gives it back, so failures do not use up a cap. Tasks already accepted are not stopped when a cap is reached.

At a cap the answer is 402 spend_limit_reached, with the period, the limit, what was spent and when it resets in details. resets_at is null for the lifetime cap.

Ask a key about itself

GET /v1/keys/self returns the key's caps, what it has spent in each period, when each resets, and its expiry.

Advice

Five points, in the order to act on them:

• Keep keys on a server. Never in a web page, a mobile app or a repository.
• Give each service its own key, with a name that says where it runs, so one can be revoked without touching the others.
• Set an expiry, and replace keys on a schedule: create the new one, deploy it, revoke the old one.
• Set a spend cap on every key. A leaked key with a daily cap costs at most that cap per day.
• If a key leaks, revoke it first and investigate second. Then open Tasks filtered to that key to see what it did: every task records the key that created it.