MassRelay
GuidesAPI referenceRun it yourselfChangelogopenapi.json

Home / Docs / Authentication

Authentication

The relay key, its scopes, and what the router answers when the key is missing or short of a scope.

Use this page to authenticate requests and to issue keys for your own users. Every endpoint under /v1 takes a relay key as a bearer token.

Send your key

Pass the key in the Authorization header: Authorization: Bearer mrk_<prefix>_<secret>.

HTTP
GET /v1/models HTTP/1.1
Host: api.massrelay.ai
Authorization: Bearer mrk_<prefix>_<secret>

A missing, malformed, unknown, revoked or expired key all get the same answer: a 401 with code invalid_api_key and a WWW-Authenticate header. The answer never confirms which keys exist.

Create and manage keys

A workspace member with the right role creates, limits and revokes keys on the Keys page of the console. A key has a policy of its own (allowed models, a budget envelope, a guardrail), set through the console. The secret is shown once, when the key is created.

Read a key's scopes and spend back with GET /v1/key (see Credits and usage).

Scopes

A key carries scopes. An endpoint that needs a scope the key lacks answers 403 with code insufficient_scope, and the answer names the scope it wanted in massrelay.requiredScope. The explain endpoint, for one, needs the explain scope.

Provision keys for your users

A workspace admin can issue a management key: a key with the keys:manage scope, created on the Keys page with an explicit confirmation. It does one thing: it mints, lists, changes and revokes keys for your own users under /v1/management/keys.

  • **POST /v1/management/keys** — mints a key. Body: scopes (any of chat, models, explain; default chat), label, endUser, expiresAt (ISO 8601), budgetEnvelopeId. The answer carries the key once, with Cache-Control: no-store.
  • **GET /v1/management/keys** — lists the keys this management key minted. Never a secret or a hash.
  • **GET /v1/management/keys/{id}** — returns one of them.
  • **PATCH /v1/management/keys/{id}** — sets expiresAt and/or budgetEnvelopeId. An expiry cannot be cleared.
  • **DELETE /v1/management/keys/{id}** — revokes the key. The row stays; a second call keeps the first time.

A provisioned key inherits the management key's policy profile and budget envelope unless you name another envelope of the same workspace. These rules apply:

  • A provisioned key never carries keys:manage: 400 scope_not_delegable.
  • A provisioned key is never an L0 or bring-your-own-upstream key: 400 field_not_allowed.
  • An envelope that is not in the same workspace: 400 envelope_not_found.
  • Your workspace's key ceiling applies. Past it the answer is 409 key_limit, and massrelay.limit and massrelay.active say where you stand.
  • A key that is not yours to manage (another management key's, another workspace's, one made in the console) answers 404, the same as a key that does not exist.
  • If the workspace holds these actions for review, a write answers 202 with a proposalId and changes nothing.

Rate limits

Requests over the limit answer 429 with a Retry-After header. See Limits.

Console endpoints

The console's own endpoints under /api take a signed-in session, not a relay key. The reference states, for every endpoint, which of the two it takes.