Authentication
API keys, how they scope to a merchant, and their lifecycle.
Calls to the Tekmerion API are authenticated with an API key. A key identifies the caller as exactly one merchant and carries that merchant's access scope. There is no separate account login at the API layer — the key is the credential.
What a key is
An API key is a Tekmerion-issued credential bound to a single merchant_id. Each key has stable lifecycle metadata:
| Field | Type | Meaning |
|---|---|---|
api_key_id | string | Canonical identity of the key. Stable for the key's lifetime. |
merchant_id | string | The single merchant this key authenticates as. |
created_at | timestamp | When the key was issued. |
revoked_at | timestamp | null | When the key was revoked; null while the key is active. |
The api_key_id identifies the key record, not the secret. The secret value itself is never returned by a read and is never part of this metadata.
Scoping
- A key authenticates the caller as one merchant. It MUST NOT grant access to any resource owned by a different
merchant_id. - The merchant a request operates on is determined by the key, not by a
merchant_idsent in the request. A request MUST NOT use one merchant's key to act on another merchant's data. - Any
merchant_idvalue supplied in a request body or path parameter is treated as a claim and verified server-side against the key's authorized scope. A value that does not match — or any attempt to act on a merchant the key is not authorized for — results in403 FORBIDDEN. The caller-supplied identifier is never trusted on its own. - Possession of a valid, non-revoked key is authentication. Privileged control-plane actions are gated by additional authorization beyond the key; a valid key alone does not authorize every action.
Lifecycle
A key is either active (revoked_at is null) or revoked (revoked_at is set). The two transitions are issuance and revocation.
Issuance and rotation
- Issuing a key creates a new
api_key_idfor the targetmerchant_idwithrevoked_at = null. - A merchant has at most one active key. Issuing a new key for a merchant that already has an active key invalidates the previous active key — the new key becomes the only active one. There is no multi-key fan-out for a single merchant.
- Because issuance is regenerate-only, rotation is "issue a new key": the act of issuing the replacement is what retires the old one. Update your stored credential to the new secret immediately; the previous key stops authenticating once it is invalidated.
Revocation
- Revocation is explicit and targets one
api_key_id. It setsrevoked_atand takes effect for subsequent requests. - A revoked key MUST NOT authenticate any request. Treat revocation as immediate and irreversible — to regain access, issue a new key.
Presenting the key on a request
Present the key in the HTTP Authorization header as a bearer credential:
Authorization: Bearer <api_key>The <api_key> is the full secret value issued to you. Issued keys carry a fixed
tek_ prefix followed by an opaque high-entropy string; treat the entire value —
prefix included — as the secret, and send it verbatim. Do not parse, split, or
transform it.
The secret value is shown once, at issuance, and is not retrievable afterward — store it securely the moment you receive it. A read of a key returns its metadata only (see What a key is); it never returns the secret. If you lose the secret, issue a new key.
These rules hold:
- A request that presents no key, an unrecognized key, or a revoked key MUST be rejected as unauthenticated.
- The secret value MUST be treated as sensitive. It MUST NOT be embedded in client-side code, URLs, logs, or any surface reachable by a customer.
- The secret is verified against a stored one-way hash; it is never stored in retrievable form. This is invisible to you on the wire but is why a lost secret cannot be recovered, only replaced.