Authentication - Refmatter

API keys

Send the key as a bearer token. A key is bound to one workspace and carries scopes.

curl https://api.refmatter.com/v1/references \
  -H "Authorization: Bearer $REFMATTER_API_KEY"

Scope	Allows
`ingestions:write`	Create and cancel ingestions
`ingestions:read`	Read ingestion state
`references:read`	List and read references
`references:write`	Annotate, delete, and manage media holds
`media:read`	Create short-lived download URLs

Keys are shown once at creation and stored as a digest. Revoke a key with DELETE /v1/workspaces/{workspaceId}/api-keys/{keyId}; revocation is immediate.

Sessions (people)

Workspace owners sign in with POST /v1/auth/sessions and receive an HttpOnly cookie. State-changing session requests must carry an Origin header equal to the web origin. Sessions are how owners create API keys:

curl -X POST https://api.refmatter.com/v1/workspaces/$WORKSPACE_ID/api-keys \
  -b cookies.txt -H "Origin: https://refmatter.com" \
  -H "Content-Type: application/json" \
  -d '{"name":"agent","scopes":["ingestions:read","ingestions:write","references:read","references:write","media:read"]}'

A request that carries both a session cookie and a bearer token is rejected with credential_conflict.

Request ids

Send X-Request-Id to correlate a call with your own logs; it is echoed back on every response and included in error envelopes.