API Keys

Authenticate external services (N8N, custom scripts, etc.) to call Ragtime API endpoints using project-scoped API keys.

Setup

Go to Dashboard → Assistant → API Keys tab in your project.
Click Create API Key and give it a descriptive name.
Select the scopes the key should have access to.
Copy the key — it’s shown only once. Store it securely.

Key Format

Keys are prefixed with rt_live_ for easy identification in logs and leak detection:

rt_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345

Only a SHA-256 hash of the key is stored server-side. The raw key cannot be recovered.

Authentication

Include the key in the Authorization header as a Bearer token:

curl -X POST https://your-ragtime-instance.com/api/v1/projects/{projectId}/libraries/{libraryId}/ingest \
  -H "Authorization: Bearer rt_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/doc.pdf"}'

Scopes

Each key is limited to specific operations via scopes:

Scope	Allows
`ingest`	Upload and manage knowledge base content via the ingest API.
`analytics:read`	Read analytics and usage data from the analytics API.
`insights:read`	Read conversation insights (sentiment, topics, outcomes) from the insights API.
`insights:write`	Create, update, and delete saved insight queries.
`recipients:read`	List and fetch personalized recipient links and their state.
`recipients:write`	Create, update, and delete personalized recipient links via the recipients API.
`distill:read`	List and fetch distillation lenses and library distillation status.
`distill:write`	Create/manage lenses, run library or recipient distillation, set retrieval mode.
`audience:read`	Read the audience labels restricting a library.
`audience:write`	Replace a library’s audience labels.
`assistant:read`	Read the assistant’s instructions and Agent Graph via the Assistant Config API.
`assistant:write`	Update the assistant’s instructions and Agent Graph.

audience:write is the most sensitive scope: it controls who can retrieve a library, and clearing the labels exposes that library to every visitor of the project. It is kept separate from ingest on purpose, so an ingestion connector cannot widen access even if its credential leaks. Grant it only to the job that genuinely owns group membership.

Library-Scoped Keys

By default a key can act on every library linked to its project. When creating a key you can optionally restrict it to a single library — useful when a separate upstream system pushes content for one audience only, and you don’t want a leaked credential to be able to write into a sibling library.

Set Restrict to library in the create dialog. The library must already be linked to the project.

A restricted key is accepted only on endpoints that address that exact library in their path:

Endpoint	Restricted key
`POST /api/v1/projects/{p}/libraries/{libraryId}/ingest`	Only if `{libraryId}` matches
`GET /api/v1/projects/{p}/libraries/{libraryId}`	Only if `{libraryId}` matches
`PATCH /api/v1/projects/{p}/libraries/{libraryId}`	Only if `{libraryId}` matches
`POST /api/v1/projects/{p}/libraries/{libraryId}/distill`	Only if `{libraryId}` matches
`GET /api/v1/projects/{p}/libraries/{libraryId}/audience`	Only if `{libraryId}` matches
`PUT /api/v1/projects/{p}/libraries/{libraryId}/audience`	Only if `{libraryId}` matches
Every other endpoint (analytics, insights, recipients, …)	Rejected

This is deliberately fail-closed: an endpoint that does not name a target library cannot satisfy the restriction, so it returns 401 rather than falling back to project-wide access. If you need a key for analytics or recipients, create an unrestricted key with just those scopes.

Deleting the library deletes the key. A restricted key has no meaning without its library, and silently widening it to project-wide access would be a privilege escalation — so the key is removed along with the library. Reissue a new key if you recreate the library.

Library scoping is orthogonal to audience labels: scoping controls what a key may write, audience labels control what a visitor may read.

Error Responses

If the key is missing, invalid, expired, or lacks the required scope, the API returns:

Status	Meaning
`401`	Missing or invalid API key.
`403`	Key is valid but lacks the required scope for this endpoint.

Using with N8N

In N8N, use an HTTP Request node.
Set Authentication to Generic Credential Type → Bearer Auth.
Bearer Token: rt_live_your_key_here

For a detailed walkthrough — including the alternative Header Auth option — see the N8N Setup Guide.

Security Best Practices

Use the minimum scopes needed for each integration.
Restrict a key to a single library when the integration only ever writes to one.
Create separate keys per integration so you can revoke one without affecting others.
Store keys in environment variables or a secrets manager — never commit them to version control.
Rotate keys periodically; delete unused keys promptly.