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-keyheader.
Create an API Key
Sign in and create one on the Agent API Key page. Rules:
- 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 / account 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.co/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 supports GET /api/account/keys, POST /api/account/keys, and DELETE /api/account/keys, requiring account. Creation accepts name, expiresIn (seconds), and a permissions array; deletion accepts keyId. Delegated keys cannot exceed the calling key's scopes or expiry.
Administrators can select “Administrator key” on the key page or request the admin scope. Each admin API call checks both that scope and the account's current administrator role. Role revocation takes effect immediately; ordinary keys do not inherit admin authority.
Profiles, avatars, notifications, repository management and author claims accept scoped keys. Organization, invitation, session, password and two-factor endpoints under /api/auth/** require account; their generated OpenAPI schema is available at /api/auth/open-api/generate-schema. Existing password, verification-code, provider-consent and payment-confirmation requirements remain in effect.
Existing keys do not automatically gain account or admin; create a replacement on the key page when needed. See /api/openapi.json and Platform operations for the complete business endpoint inventory.
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.
account covers keys, passwords, account deletion, sessions and authentication settings. admin covers all /api/admin/** endpoints. Authorization: Bearer <key> is also supported.