Authentication

Authenticated MeshQu API calls require two headers:

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

Public paths

The paths below require neither an API key nor a tenant header. Public receipt and form identifiers must be handled as access capabilities: a caller who has one may be able to read the corresponding resource, subject to the endpoint’s limits. Infrastructure:

GET /v1/health
GET /v1/.well-known/signing-keys
the OpenAPI document and docs UI, when the operator enables them

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.
Key preview — a safe prefix-and-suffix fragment (e.g. mqu_...c123) returned as key_preview in key metadata 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`	Remove tenant members. An API key that holds it is refused 403 `HUMAN_PRINCIPAL_REQUIRED` on invite and role update
`api-keys:admin`	Create, list, and revoke API keys

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