API authentication

Programmatic access to the nara API uses API principal tokens — organization-bound bearer tokens issued by your nara operator. Each principal is bound to one assistant profile and one approver; runs execute with that profile’s capabilities.

API principal tokens

A token identifies its API principal within your organization, not an individual user. It grants API access within your license tier; the bound profile scopes what runs can do.

Tokens have the format nara_sa_ followed by a random suffix, for example:

nara_sa_9fK2mQ7xR4tW8vLpN3jH6bC1dY5sA0eZgUoIiT-uXnM

nara stores only a SHA-256 hash of each token. The full value is shown once at generation time; afterwards only the first characters are displayed as a prefix so you can identify the token. Copy the token immediately and store it in a secret manager.

Getting a token

1. Ask your nara operator to create an API principal for your organization, naming the assistant profile it should run with and who may approve its actions.

2. The operator hands you the token exactly once at creation. It cannot be retrieved again later.

3. Store it in a secret manager and send it as a bearer token.

Token kinds

Kind	Expiry	Behavior
Long-lived	Optional	Valid until revoked or expired
Short-lived	Required (expiresAt)	Valid until the expiry timestamp
Single-use	Required (expiresAt)	Automatically revoked after its first request

Revoking and rotating

Revoke a token at any time to invalidate it immediately. To rotate, generate a new token, update your clients, then revoke the old one. Each token records a lastUsedAt timestamp on every request, so you can spot stale or unexpected usage before revoking.

Authenticating requests

Send the token in the Authorization header of every request:

curl https://app.nara.de/api/v1/runs/{runId} \
  -H "Authorization: Bearer nara_sa_..."

Write requests (POST, PUT, PATCH) must also set Content-Type: application/json:

curl -X POST https://app.nara.de/api/knowledge/objects \
  -H "Authorization: Bearer nara_sa_..." \
  -H "Content-Type: application/json" \
  -d '{ "typeId": "…", "contents": { "key": "value" } }'

Clerk user JWT

Instead of a principal token, you can authenticate as a user with a Clerk-issued JWT. Because a user can belong to multiple organizations, add the Clerk-Organization-Id header to select the organization:

curl https://app.nara.de/api/knowledge/types \
  -H "Authorization: Bearer <clerk-jwt>" \
  -H "Clerk-Organization-Id: <organization-id>"

Error codes

Status	Meaning
400	Invalid request body or parameters
401	Missing, invalid, expired, or revoked token
402	Insufficient credits to perform the operation
403	Permission denied (for example, admin required)
404	Resource not found
500	Internal server error

Security practices

• Never commit tokens to source control. Keep them in environment variables or a secret manager.
• Rotate tokens regularly and immediately after any suspected exposure.
• Prefer short-lived or single-use tokens for automation that runs infrequently.
• Review lastUsedAt timestamps to detect unused tokens and revoke them.

For the available endpoints, see the API reference.