> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runtimelabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and Headers

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

| Header        | Value             | Required | Notes                                 |
| ------------- | ----------------- | -------- | ------------------------------------- |
| Authorization | Bearer API\_KEY   | Yes      | API token for request identity        |
| Content-Type  | application/json  | Yes      | All requests use JSON format          |
| X-Agent-ID    | string (optional) | Optional | Identifies agent within team          |
| X-User-ID     | string (optional) | Optional | For 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:

```json theme={null}
{
  "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

| Status | Meaning           | Likely Cause                          |
| ------ | ----------------- | ------------------------------------- |
| 401    | Unauthorized      | Missing or invalid API key            |
| 403    | Forbidden         | API key lacks permission for endpoint |
| 429    | Too Many Requests | Rate 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 →](/Users/derekrosenzweig/Documents/GitHub/mintlify-docs/concepts/google-calendar.mdx)**

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.