Authentication

Every request to the Prelim API needs an Authorization header. Two token types are accepted: an API key you mint in the dashboard, and an OAuth bearer token issued through the MCP consent flow. Both are interchangeable against any endpoint.

API keys

API keys are the recommended option for scripts and backend integrations. They are scoped to your organization and never expire on their own.

Mint a key

Open Settings → API keys in the dashboard, click Create new key, give it a name (e.g. Personal laptop), and copy the secret. The full secret is shown exactly once. Store it somewhere safe like a password manager or your CI secret store.

Key format

Keys look like prelim_ followed by 43 random base64url characters, 50 characters total. The first 12 characters (the prefix) are stored in plaintext so you can identify a key later in the dashboard; the rest is stored as a SHA-256 hash.

Use the key

Send the key as a bearer token in the Authorization header on every request.

curl https://api.prelim.chat/api/auth/user \
  -H "Authorization: Bearer prelim_8s4kZxQv3p2nLw1HfYBgRmTcEsK9aJdN0iUyXoVbPeWzCqA"

Revoke a key

From the same API keys page, click Revoke next to the key. Revocation is soft: the row stays so you can audit who held a key named Hireology import last May, but any request with that secret immediately returns 401.

OAuth tokens

OAuth 2.1 with PKCE is used by the MCP server. When you connect Claude.ai or another MCP host to Prelim, you sign in, click Allow, and the host receives a short-lived bearer token bound to your account and audience.

OAuth tokens work against any REST API endpoint too. See the MCP overview for the connection flow; you do not need to drive the OAuth dance yourself unless you are building an MCP client.

Header format

Whichever token you use, send it as:

Authorization: Bearer prelim_8s4kZxQv3p2nLw1HfYBgRmTcEsK9aJdN0iUyXoVbPeWzCqA

A missing or malformed header returns 401 Authorization token required. See Errors for the full table.