API keys

Open app.auray.ai, then Account → API Keys.

#Minting one

New key asks for four things:

• A name. For you; it appears in GET /v1/usage beside the key's spend.
• A spending cap. Follow my plan holds the key to your plan's monthly credits in force, a promotion's lift included, and moves with the plan when it changes. While your plan grants no monthly credits, a key that follows it has no monthly cap of its own: your balance is its only limit. A fixed cap holds it to a whole number you type — up to the plan's monthly credits while the plan grants some, and up to 1,000,000 while it grants none. Once the key has spent its cap in a calendar month (UTC) it stops generating until the next one begins, and the rest of the account is untouched either way. Zero is not accepted, because zero is how this column spells no cap at all.
• When it expires. 30, 90, 180 or 365 days; no key lasts forever.
• Scopes. Reading jobs and assets is always included. Every write scope starts ticked, so a key works the moment it is minted; untick anything this key should not be able to do. Each one says in a line what it lets the key do. chat:read, below them under What else it may read, starts unticked: it reads back every chat thread of the account and what was typed in it, the Messages app's included, so a key holds it only if you tick it. Authentication lists all 19 of them.

A key's scopes are fixed when it is minted. To change what one may do, revoke it and mint another — a credential whose powers can grow is a credential whose leak gets worse after the fact.

The key is shown once. It starts with auray_sk_ and is 71 characters. Copy it into the environment your code reads it from — the examples in this documentation use AURAY_API_KEY.

#Reading the pane

Each row is one key: its name, its ID (printed ID and the twelve characters after the prefix, which is all the pane can show), when it was made, when it was last used and when it expires, then what it may make, by the names the create sheet gives its write scopes (Images, Video, Text and the rest) — or read-only if it may make nothing — followed by reads chats when the key holds chat:read, and what it has spent this month against its cap, which says whether it follows your plan, is a fixed cap, has no cap, or is a cap set by our team. Its scopes, its cap and its spend come back from GET /v1/me for the key making the call, and its spend from GET /v1/usage for all of them.

A key within 14 days of its date says how many are left, in amber. One that has expired stays on the list, marked expired, for 30 days: it holds no place among the keys your plan allows, and it is there so the key a script stopped on is one you can find.

Cap on a key's row changes its cap: to your plan's, or to another whole number up to the plan's monthly credits — up to 1,000,000 while the plan grants none — looser as well as tighter. What the key spent this month stays counted against the new figure.

A key made before this choice was offered follows your plan only if, on the day the choice arrived, the cap it held was your plan's monthly credits in force, a promotion's lift included. Every other one keeps the cap it held that day — or none, if it held none — until you change it here. The row says which each key holds: your plan, a fixed cap, no cap, or a cap set by our team.

A cap our team sets on a key binds it: Cap then offers only a figure, which you may lower and raise back as far as the one our team set, and the key cannot follow your plan or go above that figure until our team changes it.

The ID names a key; it is not the key and cannot call the API. Sent as one — with or without auray_sk_ in front — it is refused 401 invalid_api_key with a sentence that says so. If the key itself is lost, revoke it and mint another: nobody can show it again.

#Revoking

Revoke stops a key: the next request that spends, writes or downloads with it answers 401 key_revoked at once, and one that only reads — a status poll, a result, a chat thread — within 2 seconds. To rotate, mint the new key, deploy it, then revoke the old one — both work at once, so there is no window where neither does.

Sign out everywhere, under Account → Profile & Security, ends every session of the account and can revoke every key you made with it, in one step — for the day a laptop goes missing.

The desktop's own session keys are not listed here. They are minted for the browser session, last 12 hours, and are revoked on sign-out — and when that session is ended from another device.

#Webhooks

Each endpoint's row says which products it sends — every product, unless it was added with a list — whether it is receiving, when a delivery last succeeded and last failed, and, when it was switched off, why. New endpoint asks for the URL and which products to send — every product unless you pick some — and says where the public keys that verify each signed delivery are published. Webhooks covers the signature.