API authentication

Programmatic access to the nara API uses server tokens — organization-bound bearer tokens generated by administrators in the webapp.

Server tokens

A server token identifies your organization, not an individual user. It grants full API access within your license tier; there are no per-token scopes.

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.

Generating a token

1. Open Admin > Settings.

2. In the Server token section, select Generate (or Regenerate to replace an existing token).

3. Copy the displayed token. It cannot be retrieved again later.

Generating and managing tokens requires the serviceAccount.manage permission, which the built-in Admin role includes by default.

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/agent/run \
  -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/memory/objects \
  -H "Authorization: Bearer nara_sa_..." \
  -H "Content-Type: application/json" \
  -d '{ "typeId": "…", "contents": { "key": "value" } }'

Clerk user JWT

Instead of a server 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/memory/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.