API Tokens

API tokens authenticate all requests to the Ogarni.AI API. Every request must include a valid token in the X-API-Key header.

Creating a token

1. Download the Ogarni.AI mobile app (App Store | Google Play)
2. Log in to the app
3. Navigate to Settings > API Tokens
4. Click Create token
5. Choose a name (e.g., “My script”) and a scope
6. Click Create
7. Copy the token immediately

Important: The token is displayed only once at creation. If you lose it, you will need to create a new one.

Token format

All tokens use the oai_ prefix followed by a base64url-encoded payload and HMAC-SHA256 signature:

oai_eyJzdWIiOiIxMjM0NTY3ODkw...

The oai_ prefix makes it easy to identify Ogarni.AI tokens in your configuration and to set up secret scanning in your repositories.

Using the token

Include the token in the X-API-Key header of every request:

curl -X GET "https://api.ogarni.ai/api/weekly-summaries/latest" \
  -H "X-API-Key: oai_your_token_here"

Token scopes

Each token is assigned a scope that determines what it can access:

Scope	Access level	Rate limit
read	Read-only access to all resources	1,000 requests/hour
write	Read and write access	2,000 requests/hour
admin	Full access including token management	5,000 requests/hour

Recommendation: Always use the most restrictive scope that meets your needs. For most integrations and scripts, read is sufficient.

Security best practices

1. Store tokens in environment variables. Never hardcode them in source code.

   export OGARNIAI_API_TOKEN="oai_your_token_here"

2. Use the read scope unless you specifically need write or admin access.

3. Rotate tokens regularly. We recommend rotating every 90 days. Create a new token, update your configuration, then delete the old one.

4. Never log tokens. Avoid printing tokens to console output or writing them to log files.

5. Use HTTPS only. All API endpoints require HTTPS. Plain HTTP requests will be rejected.

6. Set up secret scanning. The oai_ prefix makes it straightforward to detect accidentally committed tokens using tools like GitHub secret scanning or git-secrets.

Revoking a token

To revoke a token:

1. Go to Settings > API Tokens in the app.
2. Find the token you want to revoke.
3. Click Delete.

The token becomes invalid immediately. Any requests using it will receive a 401 Unauthorized response.