Chronologue uses token-based authentication to secure API access between clients (frontend interfaces, agents) and the backend (FastAPI application and memory store). Every API request must include an Authorization header containing a valid API key.

This document outlines how to authenticate requests, what headers are required, and how to manage access securely.

​
API Key Authentication

​
Obtaining an API Key

API keys are issued per user or agent during onboarding or account setup. You may request a key from the Chronologue admin interface or via developer onboarding tools.

​
Sending the Key in Requests

All requests must include the following header:

Header:

Authorization: Bearer YOUR_API_KEY

Example:

Authorization: Bearer sk-xyz123abc456

​
Required Headers

HeaderValueRequiredNotes
AuthorizationBearer API_KEYYesAPI token for request identity
Content-Typeapplication/jsonYesAll requests use JSON format
X-Agent-IDstring (optional)OptionalIdentifies agent within team
X-User-IDstring (optional)OptionalFor impersonation or system-use cases

​
Example Request

Example: Push memory trace

POST /memory/push

Headers:

Authorization: Bearer sk-test-user-key
Content-Type: application/json

Payload:

{
  "type": "goal",
  "task_id": "goal-2025-05-10-train-model",
  "timestamp": "2025-05-10T10:00:00Z",
  "content": "Train model on latest trace dataset",
  "importance": 4
}

​
Token Expiration and Rotation

  • API keys do not expire by default unless scoped with TTL.
  • You may rotate keys by requesting a new one via dashboard or API.
  • Revoke compromised keys immediately.
  • Audit usage periodically if running multiple agents.

​
Security Best Practices

  • Never expose keys in browser code or public repositories
  • Store credentials in .env files or secret managers
  • Use scoped keys per agent or per role when possible
  • Enforce HTTPS to protect credentials in transit

​
Troubleshooting Authentication Errors

StatusMeaningLikely Cause
401UnauthorizedMissing or invalid API key
403ForbiddenAPI key lacks permission for endpoint
429Too Many RequestsRate limiting applied

​
OAuth-Based Authentication (External Services)

Chronologue APIs use token-based headers, but integrations like Google Calendar use OAuth 2.0 for user-granted permissions.

If you’re connecting memory traces to Google Calendar, see the full guide:

Google Calendar Integration →

This explains how to authenticate with Google, obtain tokens, and sync .ics-based events from memory traces.

Chronologue separates authentication into two layers:

  • Internal (API Keys): secure, lightweight, system-to-system communication
  • External (OAuth): used for delegated access to third-party services like calendars

Use headers carefully to ensure agent behavior is traceable, auditable, and secure across time.