Authentication

Every request to the MeshQu API (except health and readiness checks) requires two headers:

Header	Description
`Authorization`	`Bearer <API_KEY>`
`X-MeshQu-Tenant-Id`	Your tenant UUID

API keys

API keys are created via the /v1/api-keys endpoint (requires the api-keys:admin scope) or through the MeshQu Console. When you create a key, the plaintext value is returned exactly once. Store it securely — it cannot be retrieved again. The API stores only a hashed representation. Each key has:

Name — a human-readable label for audit trails.
Scopes — the set of permissions the key grants (see below).
Expiry (optional) — an expires_at timestamp after which the key is rejected.
Prefix/suffix — a safe fragment (e.g. mqu_...c123) shown in dashboards for identification.

Keys are mqu_ followed by a base64url-encoded random token (e.g. mqu_EXAMPLEKEYdonotuse_replace_with_ownx_abc123). There is no environment segment such as _live_ or _test_ — a single key format is used everywhere.

Revoking a key

DELETE /v1/api-keys/:id

Revoked keys are rejected immediately. Revocation is permanent.

Scopes

Each API key carries one or more scopes that control what it can access:

Scope	Grants access to
`policies:read`	List and read policies, versions, groups
`policies:write`	Create, update, deactivate policies and groups
`decisions:evaluate`	Evaluate decisions (dry-run)
`decisions:read`	List and read recorded decisions
`decisions:write`	Record decisions (evaluate + persist)
`alerts:read`	List and read alerts
`alerts:write`	Acknowledge alerts, manage webhook subscriptions
`audit:read`	Read audit events
`audit:admin`	Verify audit log integrity
`members:read`	List and read tenant members
`members:write`	Invite, update, and remove tenant members
`api-keys:admin`	Create, list, and revoke API keys

A tenants:provision scope also exists for cross-tenant operator keys, but it is not grantable through the API — an api-keys:admin key cannot mint itself one. It is assigned out-of-band by MeshQu operators only.

Principle of least privilege: create separate keys for different services. A service that only evaluates decisions needs decisions:evaluate — not api-keys:admin.

Multi-tenancy

All data in MeshQu is isolated per tenant. The X-MeshQu-Tenant-Id header determines which tenant’s data is accessed. The API key must belong to the specified tenant; a mismatch returns 403 Forbidden.

Rate limits

MeshQu applies two tiers of rate limiting:

Tier	Scope	Default limit
Pre-authentication	Per IP address	10,000 requests/minute
Post-authentication	Per tenant + API key	1,000 requests/minute

When a limit is exceeded the API returns 429 Too Many Requests with a Retry-After header. Standard rate-limit headers are included on every response:

rate-limit-limit: 1000
rate-limit-remaining: 997
rate-limit-reset: 1700000060

Example: creating an API key

curl -X POST https://api.meshqu.com/v1/api-keys \
  -H "Authorization: Bearer ADMIN_KEY" \
  -H "X-MeshQu-Tenant-Id: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "trade-service-prod",
    "scopes": ["decisions:evaluate", "decisions:write"]
  }'

Response (key shown once):

{
  "key": {
    "id": "key_uuid",
    "tenant_id": "tenant_uuid",
    "name": "trade-service-prod",
    "key_preview": "mqu_...c123",
    "scopes": ["decisions:evaluate", "decisions:write"],
    "expires_at": null,
    "last_used_at": null,
    "is_active": true,
    "created_at": "2025-01-15T10:00:00Z",
    "created_by": null,
    "revoked_at": null,
    "revoked_by": null
  },
  "plaintext_key": "mqu_EXAMPLEKEYdonotuse_replace_with_ownx_abc123"
}

Store the key value immediately — it will not be returned again.

Getting Started

Concepts

API Reference

SDK

Guides

Recipes

Security

Meta

API keys

Revoking a key

Scopes

Multi-tenancy

Rate limits

Example: creating an API key

​API keys

​Revoking a key

​Scopes

​Multi-tenancy

​Rate limits

​Example: creating an API key

API keys

Revoking a key

Scopes

Multi-tenancy

Rate limits

Example: creating an API key