API authentication and keys

Every v1 API request carries an API key in the X-API-KEY header. A key belongs to an admin account and can do exactly what that admin's roles allow. This page covers creating and rotating keys, how permissions apply, and what a 401 means.

Create a key

1. Sign in to the admin as an admin who can manage administrators.
2. Open People > Admins and select the admin that the integration will act as.
3. In the API keys card, select Create API key.
4. Copy the key now. Raytha stores only a hash, and shows the key once.

Then send it with every request:

curl -s "$RAYTHA_URL/raytha/api/v1/Ping" \
  -H "X-API-KEY: $RAYTHA_API_KEY"

The header name is not case-sensitive. A key is a 36-character GUID string. Each admin can hold up to 10 keys, so you can issue one per integration and revoke them independently. The matching user guide page, Create an API key for the Headless REST API, has the same steps with screenshots.

Give the key a narrow role

Raytha does not have scoped keys. A key inherits its admin's roles. To limit what an integration can do, make a dedicated admin account and give it a dedicated role:

1. Open People > Roles and create a role. Grant only the system permissions the integration needs, and set read, edit or config access for each content type it touches.
2. Create an admin for the integration and assign that role.
3. Create the key on that admin.

What permissions the endpoints need

Permission	Allows
Content type: read	List and read items of that type. Look up a route.
Content type: edit	Create, edit, unpublish, discard drafts, trash items, batch create, set the home page, assign templates.
Content type: config	List the trash, restore items, delete from the trash, and edit that type's fields and views.
media_items	List and delete media. Upload permission alone allows uploads.
content_types	Create and delete content types and menus.
templates	Themes, web templates and widget templates.
site_pages	Site pages and widgets.
users	Public users and user groups.
system_settings	Raytha Functions.
Any admin	Ping and BackgroundTasks.

A read-only key for a static site build needs a role with read on the content types you publish, and nothing else.

Revoke and rotate

1. Create the new key on the same admin.
2. Deploy it to the integration.
3. In the API keys card, revoke the old key.

Deactivating or deleting an admin stops all of its keys. The next request returns 401.

Store the key safely

• Keep it in an environment variable or your host's secret store. Do not commit it.
• The Raytha CLI and the examples in this documentation read RAYTHA_URL and RAYTHA_API_KEY. Those names are a convention of the examples, not settings of the server.
• Never embed a key in a web page or a mobile app. Anyone can read it.

Errors you will see

Status	Detail	Cause
401	Invalid API key.	The header is missing or empty, the key does not exist, it was revoked, or its admin is inactive.
401	Unauthorized access.	The key is valid, but its admin lacks the permission for this endpoint or content type.

Raytha answers a missing permission with 401, not 403. Tell the two apart by the detail text. See Errors.

Gotchas

• The secret appears once. If you lose it, create another key. There is no way to read an existing one.
• The key stops with its admin. A suspended or deleted admin silently breaks every integration using its keys.
• Each admin holds at most 10 keys. Revoke unused ones to create more.

Next steps

• REST API overview: the URL layout and conventions.
• Content items: make your first write.
• Errors: every failure shape and how to handle it.
• Authentication and single sign-on: sign-in for people, which is separate from API keys.