Core concepts

Authentication

How API keys, scopes and tenant headers work together on every request.

Every request is authenticated with a key that is scoped to a single tenant. This page is a placeholder for that contract.

The API key#

Send the key as a bearer token. Keys are per tenant and per environment, so a staging key can never read production data.

GET /v1/customers HTTP/1.1
Host: api.verlix.example
Authorization: Bearer vx_live_...

Never ship a live key

A key in a browser bundle is a public key. Proxy requests through your own backend and keep the key server-side.

Scopes#

Scope	Grants
`customers:read`	Read customer records
`customers:write`	Create and update customers
`invoices:read`	Read invoices and credit notes
`invoices:write`	Issue, void and send invoices

Choosing scopes#

Grant the narrowest scope that lets the integration work. A read-only reporting job should never carry a write scope, because a bug in that job would then be able to mutate billing data.

Verify a key#

GET/v1/auth/whoami

Returns the tenant, environment and scopes for the presented key.

Field	Type	Notes
`tenantId`	string	The tenant the key belongs to
`environment`	string	`live` or `test`
`scopes`	string[]	The granted scopes

curl -H "Authorization: Bearer $VERLIX_API_KEY" \
  https://api.verlix.example/v1/auth/whoami

Rotating a key#

Create the replacement
Issue a new key with the same scopes. Both keys work while you migrate.
Deploy the new key
Roll the new value out to every service that calls the API.
Revoke the old key
Revoke the previous key once traffic has moved. Revocation takes effect within seconds.