Create an API key for the headless REST API
An API key lets a script, an app or a build server call Raytha's headless REST API without a person signing in. A key always belongs to one administrator and can do exactly what that administrator's roles allow, so the first decision is who it should act as.
What you need
- The Manage Administrators permission, to create or revoke keys.
- An active administrator account for the key to belong to. For anything other than a quick test, create a separate administrator for it. See Manage administrators, roles and permissions.
Choose who the key acts as
A key has no permissions of its own. On every request Raytha looks up the administrator that owns the key and applies their current roles. Three things follow:
- If you later change that administrator's roles, the key's reach changes immediately.
- If the administrator is suspended or loses admin access, the key stops working.
- If the administrator is deleted, their keys are deleted too.
So for an integration, create an administrator such as "Website build bot", give it a role with only the permissions the integration needs (for example Read and Edit on one content type), and create the key on that account. Do not use a Super Admin key for something that only needs to read posts.
Create a key
- Open People > Admins and click the administrator.
- Find the API keys card and click Create API key.
- Click Copy next to the key under "Copy this key now. It will not be shown again."
- Store it in your password manager or your deployment's secret store.
You should now see a new row in the card reading "Created", with the date and your name, and a Revoke button. The key itself is not shown there again. Raytha stores only a hash, so nobody can recover it. If you lose a key, create another and revoke the old one.
An administrator can have up to 10 keys. At the limit the button is disabled with "This admin already has 10 API keys. Revoke one to create another." If the account is suspended, the card says "Restore this account before creating an API key."
Use the key
Send the key in an X-API-KEY header with every request. The API lives under /raytha/api/v1 on your site. This request checks that the key works:
curl -s -H "X-API-KEY: YOUR_KEY" https://example.com/raytha/api/v1/pingA success response means the key is valid and belongs to an active administrator. This one lists items of a content type called posts:
curl -s -H "X-API-KEY: YOUR_KEY" \
"https://example.com/raytha/api/v1/contentitems/posts?pageSize=10"A missing, mistyped or revoked key gets a 401 response with the message "Invalid API key." Raytha does not tell you which of the three it was. The same happens when the key's administrator is suspended. Keep keys out of web pages and public repositories: a key in browser code is visible to every visitor. For the full request and response format, see API overview and API authentication.
What a key can reach
Each group of endpoints needs a permission on the administrator the key belongs to.
| Endpoint group | Permission needed |
|---|---|
ping, background task status | Any administrator |
| Content items of one content type (list, read, create, edit, delete) | The content type's Read or Edit permission, or Manage Content Types |
| Content type fields and views (change) | The content type's Configure permission, or Manage Content Types |
| Content types, schema import and export, menus | Manage Content Types |
| Site pages | Manage Site Pages |
| Themes, web templates, widget templates | Manage Templates |
| Media items (list, delete) | Manage Media |
| Media upload | Manage Media, Manage Content Types, Manage Templates, or Edit on any content type |
| Public users and user groups | Manage Users |
| Raytha Functions | Manage System Settings |
Manage System Settings and Manage Administrators each imply all the other system permissions, so a key on such an administrator can reach everything above. See Manage administrators, roles and permissions.
The administrator screens you use in the browser (this guide's People, Settings and Observability sections) are not part of the key-based API.
Revoke a key
- Open People > Admins and click the administrator.
- In the API keys card, click Revoke beside the key.
- Confirm with Revoke key.
You should see the toast "API key revoked" and the row disappears. Anything still using that key gets 401 from the next request on. This cannot be undone.
To cut off every key of an account at once, suspend the administrator instead. Their keys keep existing but stop working until you restore the account.
Gotchas
- The key is shown once. If you navigate away before copying it, revoke it and create a new one.
- Keys do not expire. Rotate them yourself: create the new key, update your integration, revoke the old key.
- A key can act with the power of its owner. A key created on your own account can do everything you can. Prefer a dedicated account with a narrow role.
- Do not count on the audit log to name the key's owner. A key is checked on each request and does not sign anyone in, so changes made through a key may appear in the audit log without a user name. Keep a record of which integration uses which key. See View the audit logs.
- A request refused for permissions is not a bad key. If
pingworks but a content request is refused, add the missing permission to the administrator's role instead of creating another key.