Authentication

Every request to the MeshQu API requires two headers, except on the public paths listed below:

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

Public paths

These paths carry no API key and no tenant header. They are not an oversight — each hosts its own access control, and offline verification and hosted forms depend on them being reachable without a key. But the exception is wider than “health checks”, so it is set out in full: Infrastructure:

GET /v1/health, GET /v1/ready
GET /v1/.well-known/signing-keys, GET /v1/.well-known/trust-registry
the OpenAPI document and docs UI, when the operator enables them
GET /metrics — not free of tenant data. Many metric families carry a tenant label, so the endpoint exposes per-tenant volumes and outcomes. It is guarded by a bearer token (METRICS_BEARER_TOKEN, required in production), not by an API key — which is why it sits on this list at all.

Tenant-scoped, unauthenticated — these do reach tenant data, addressed by an unguessable identifier rather than by a key:

GET /v1/receipts/:decisionId and GET /v1/receipts/:decisionId/bundle
GET /v1/chains/:chainId/verify, GET /v1/chains/:chainId/seal, GET /v1/chains/:chainId/bundle
GET /v1/forms/:formId/schema, GET /v1/forms/:formId/api-contract, GET /v1/forms/:formId/receipts/:decisionId
POST /v1/forms/:formId/submit — the one public write. A submission to a hosted form is evaluated and mints a signed receipt without any API key being presented. Rate limiting is per (form, IP) and the form’s own token budget caps total consumption; treat a form’s ID as a capability and disable forms you no longer want submissions on.

“Unauthenticated” here means no API key and no tenant header — not unrestricted. Every one of these paths is rate-limited, and a request still only ever reaches the tenant that owns the identifier in the URL. What it does not do is prove who the caller is.

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

Public paths

API keys

Revoking a key

Scopes

Multi-tenancy

Rate limits

Example: creating an API key

​Public paths

​API keys

​Revoking a key

​Scopes

​Multi-tenancy

​Rate limits

​Example: creating an API key

Public paths

API keys

Revoking a key

Scopes

Multi-tenancy

Rate limits

Example: creating an API key