Authentication
Keys and scopes
Every call carries an API key as a bearer token. Keys are minted by you, on the developer platform, and each one holds only the scopes you gave it.
Sending a key
Put the key in an Authorization header on every request. There is no other authentication: no cookies, no sessions, no signing.
GET /api/v1/subjects HTTP/1.1
Host: www.revisiongenie.com
Authorization: Bearer rgk_live_YOUR_KEY_HEREKeys begin rgk_live_. The prefix is deliberate: a key pasted into a repository or a chat log is recognisable on sight, which is what makes automatic secret scanning able to find one.
Minting, revealing and revoking
- The secret is shown once. We store only a hash of it, so there is no way to show it again, for you or for us. Copy it at mint time.
- You may hold 5 live keys at once. Revoke one to make room for another. Separate keys for production and staging is the point of having several.
- Revoking is immediate. A revoked key stops working on its next call and cannot be restored.
- The platform lists what each key has done: its prefix, when it was last used and how many calls it has made. That is how you tell which key to revoke.
Your keys are your responsibility
You are responsible for everything done with your keys, whether by you, a colleague, or anyone else who obtains them. Never put a key in a mobile app, a web page, a public repository, or anywhere a user could read it. Calls should come from a server you control. If a key is exposed, revoke it in the dashboard and tell us at support@revisiongenie.com. Developer terms, section 2.
Scopes
A scope is a fence around one part of the API. A key holds the scopes you ticked when you minted it and nothing else, so a key that only talks to a genie cannot generate questions even though both come out of the same balance. Give each integration the narrowest set that works.
| Scope | What it allows | Endpoints |
|---|---|---|
| curriculum:read | Read subjects, topic trees, search and spec references. | /v1/subjects, /v1/subjects/{subjectId}/tree, /v1/search, /v1/subtopics/{subtopicId}/spec-points |
| ai:align | Match free text to our subtopics with a confidence score. | /v1/align |
| ai:knowledge | Search the subject knowledge files cleared for API use. | Reserved. Coming soon, and there is nothing to call with it yet. |
| ai:chat | Send a stateless chat message to a subject genie. | /v1/genies/{shortName}/chat, /v1/chat |
| ai:questions | Generate a set of exam-style questions for a subtopic. | /v1/questions/generate |
GET /api/v1/account needs no particular scope. Any valid developer key can read the account it spends from, because a balance check that could be refused for holding the wrong scope would be a support ticket waiting to happen.
When authentication fails
Refusals use the same { error, message } shape as everything else.
| Code | Status | When |
|---|---|---|
| invalid_key | 401 | No key, a malformed key, an unknown key, a revoked key, or an expired key. All of them return the same refusal on purpose: which one failed is only useful to somebody guessing. |
| forbidden | 403 | The key is valid but does not hold the scope this endpoint requires. Mint a key with the right scope; you cannot add a scope to an existing key. |
| suspended | 403 | The developer account is suspended. Data endpoints stop as well as billable ones. |
| rate_limited | 429 | Too many failed authentication attempts from one address, or the key went past its call ceiling. Wait a minute. |
A browser reports a refusal properly
CORS headers are attached to refusals as well as to successes, so a 401 arrives at a browser as a 401 with a readable message rather than an opaque network error. Note that Access-Control-Allow-Credentials is never set: the only credential is the header you send.
Rotating a key
There is no rotate button, because rotating in place would mean a window in which neither the old nor the new key is certain to work. Do it in this order instead: mint the new key, deploy it, confirm traffic has moved on the platform's per-key call counts, then revoke the old one.
Base URL for every example on this page is https://www.revisiongenie.com/api/v1. Rate limits and the rest of the error codes are on Errors and rate limits.