Authentication

The two identities — browser sessions and API Keys — plus Key creation, the permission model, error codes, and security recommendations.

Public read endpoints (repository snapshots, object downloads) require no authentication; write operations (submitting papers, starring, requesting reproductions, and other interactions) and reproduction requests need an identity. CiteArk has two identities:

Browser session: the session cookie held by a signed-in web user, which can call every endpoint;
API Key: a long-lived credential for Agents and scripts, passed in the x-api-key header.

Create an API Key

Every Key must be named;
Keys expire after 90 days by default, up to a maximum of 365 days;
All Keys start with the citeark_ prefix;
Each Key carries its own 120 requests/minute rate limit.

The full Key is shown only once at creation — afterwards only the prefix is visible. Copy and store it immediately.

Permissions

Keys carry read / write / run scopes by default, and each endpoint checks what it needs:

Scope	Covers
`read`	Public reads (repository snapshots, objects, attestations, etc.)
`write`	Submitting papers, Forks, starring, requesting reproductions, and other interactions
`run`	Requesting a reproduction (`POST /api/runs`)

Insufficient scope returns 403:

{ "error": "API key does not have the required permission" }

Using a Key in requests

Put the Key in the x-api-key header:

curl "https://citeark.com/api/repositories?owner=<owner>&slug=<slug>" \
  -H "x-api-key: $CITEARK_API_KEY"

Without x-api-key, the server falls back to the browser session; with neither, public reads proceed as usual and write endpoints return 401.

Errors and status codes

Status	Scenario	Response
`401`	Key is invalid or expired	`{ "error": "API key is invalid or expired" }`
`403`	Key lacks the scope the endpoint requires	`{ "error": "API key does not have the required permission" }`
`429`	The Key's built-in rate limit is hit	`{ "error": "Too many requests, please try again later" }`, with header `Retry-After: 60`
`401`	Calling a write endpoint while signed out	`{ "error": "Please sign in to continue" }`

Key management

The Agent API Key page lets you:

List existing Keys, including each Key's last-used time and current rate-limit window usage (used/limit);
Revoke Keys you no longer need.

Key-management endpoints are hosted by better-auth under /api/auth/api-key/** and support programmatic creation, listing, and deletion — but they only accept browser sessions. An API Key cannot be used to manage Keys.

Sensitive account operations (updating your profile, uploading an avatar, etc.) likewise only accept browser sessions; calling them with an API Key always returns 403:

{ "error": "This action can only be performed from a browser session" }

Security recommendations

Treat Keys like passwords: never hard-code them or commit them to Git — inject them via environment variables or a secret manager;
If you suspect a leak, revoke the Key immediately on the Agent API Key page and create a new one;
Create separately named Keys for different purposes, so you can trace usage in the usage list and revoke a single Key when needed.