API Keys

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

Setup

1. Go to Dashboard → Assistant → API Keys tab in your project.
2. Click Create API Key and give it a descriptive name.
3. Select the scopes the key should have access to.
4. 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}/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.

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

1. In N8N, use an HTTP Request node.
2. Set Authentication to Generic Credential Type → Bearer Auth.
3. 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.
• 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.