Authentication

A 2.1 request carries its key in the path, not in an Authorization header. That is a deliberate compatibility choice, not an oversight — and it runs on the same key management as v3 underneath.

One key store, not two

2.1 authenticates against the same keys as v3 — hashed secrets, expiration, status, audit, lastUsedAt, platform constraint. This page covers what is specific to 2.1: the key in the path, and its two scopes. API keys, scopes and platform constraints

The key lives in the path

Every 2.1 route carries the key as a path segment, right after the audience — client or user. This is preserved for V2 compatibility, not a new design:

http

/v2.1/client/{key}/{crid}/...
/v2.1/user/{key}/{crid}/redirect

Two scopes, two audiences

The two path families are gated by two different scopes, and a key carries whichever ones it was issued.

2.1 scopes
Scope	Path family	Grants
client_v2	/v2.1/client/{key}/...	The server-side operations — redirect (URLs, not a redirect), retarget, qrcode, card, notify, modify, details, webhook.
user_v2	/v2.1/user/{key}/...	The single browser-facing redirect used to send a recipient to their message.

Same key management as v3

A 2.1 key is not a separate credential system living alongside v3's. It is issued, stored and audited exactly like a v3 key: secrets are hashed, keys carry an expiration and a status, every call updates lastUsedAt, and a key can be constrained to a platform. Integrating both APIs means managing one set of credentials, not two.

The cost of a key in a URL

Putting a credential in a path has a consequence worth knowing before you rely on it.

Authentication errors

A 2.1 authentication failure reports as one of three codes, in the 2.1 error envelope:

json

{
  "status": 1,
  "error": "key_invalid"
}

Authentication error codes
Code	Meaning
key_invalid	The key segment in the path does not match a known, active key.
forbidden	The key is valid but does not carry the scope this route requires.
auth_unavailable	The key could not be checked because the authentication dependency was unreachable — a transient failure, not a rejection of the key.