Authentication

Every request to the Inherent API must include a valid API key. This guide covers how to create keys, attach them to requests, manage permissions, and stay within rate limits.

Creating an API Key

1. Log in to the Inherent Dashboard.
2. Navigate to Settings > API Keys.
3. Click Create API Key.
4. Select the permissions the key needs (see Permissions below).
5. Copy the key immediately — it is only shown once.

All keys are prefixed with ink_ so they are easy to identify in logs and secret scanners.

ink_a1b2c3d4e5f6...

Sending Your API Key

There are two ways to authenticate. The X-API-Key header is preferred.

X-API-Key header (preferred)

curl https://api.inherent.systems/api/v1/documents \
  -H "X-API-Key: ink_your_key_here"

Authorization: Bearer header

curl https://api.inherent.systems/api/v1/documents \
  -H "Authorization: Bearer ink_your_key_here"

If both headers are present, X-API-Key takes precedence.

Permissions

Each API key is scoped to one or more permissions. Assign the minimum set your application needs.

Permission	Grants access to	Example endpoints
read	List and retrieve documents and chunks	GET /api/v1/documents, GET /api/v1/chunks/:document_id
search	Semantic search across your knowledge base	POST /api/v1/search
write	Upload and delete documents	POST /api/v1/documents, DELETE /api/v1/documents/:id

A key with only read permission cannot perform searches or upload documents. If you call an endpoint your key is not authorized for, the API returns 403 Forbidden.

Rate Limits

Rate limits are enforced per API key on a sliding 60-second window.

Plan	Requests / minute
Starter	100
Pro	500
Business	2,000
Enterprise	10,000

Rate Limit Headers

Every response includes headers so your application can track usage:

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the current window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp (seconds) when the window resets
Retry-After	Seconds to wait before retrying (only present on 429 responses)

When you hit the limit, the API returns 429 Too Many Requests. Back off for the duration specified in the Retry-After header before retrying.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "retry_after": 12
  }
}

tip

Implement exponential backoff in production. A simple sleep(retry_after) works, but jittered exponential backoff handles bursts more gracefully.

Security Best Practices

1. Never expose keys in frontend code. API keys should only be used in server-side code or backend services. A key embedded in a browser bundle is visible to anyone with dev tools.

2. Use environment variables. Store your key in an environment variable, not in source code.

   export INHERENT_API_KEY="ink_your_key_here"

3. Rotate keys regularly. Create a new key, update your services, then revoke the old key. The dashboard supports multiple active keys to enable zero-downtime rotation.

4. Use minimum permissions. A service that only reads documents should not have a key with write permission. Create separate keys for separate concerns.

5. Monitor usage. Check the API Keys section of the dashboard to review request counts per key. Unexpected spikes may indicate a leaked key.

6. Revoke compromised keys immediately. If a key is exposed, revoke it from the dashboard and create a replacement.

danger

If you accidentally commit an ink_ key to a public repository, revoke it immediately from the dashboard. Treat any exposed key as compromised.

Error Responses

Authentication errors follow the standard error format:

Status	Code	Meaning
401	unauthorized	Missing or invalid API key
403	forbidden	Key lacks the required permission for this endpoint
429	rate_limit_exceeded	Too many requests — check Retry-After header

See the API Reference for the full error response format.