Authentication

Every request to the EmBoux API must include an API key in the Authorization header.

Header Format

Authorization: Bearer YOUR_API_KEY

Token Types

EmBoux uses two types of API keys:

Master Token

Used by the platform owner (you) for administrative operations:

• Full access to all resources across all partners
• Can create, update, and delete API keys
• Can manage any domain, mailbox, or alias
• Set via the EMBOUX_API_KEY environment variable on the server

Client Token

Issued to individual customers or integrators:

• Scoped to a single partner — can only access their own resources
• Subject to quota limits (domains, mailboxes per domain, aliases per mailbox)
• Can optionally have an expiration date — the API rejects expired tokens with 403
• Managed through the Odoo portal or via master token API calls

Discovering required roles

Endpoints that require a master token are tagged in the OpenAPI schema with x-required-role: master. SDK generators and clients can use this to surface the requirement up front instead of discovering it through a 403 at runtime:

curl -s https://api.emboux.com/openapi.json \
  | jq '.paths | to_entries[]
        | {path: .key, ops: (.value | to_entries[]
            | select(.value["x-required-role"] == "master")
            | .key)}'

When a customer token attempts a master-only call, the API responds with a unified 403 body:

{ "detail": "Master token required" }

Quota Enforcement

Client tokens carry built-in limits:

Quota	Description	Default
domains_allowed	Max domains the partner can create. 0 = unlimited	From plan
mailboxes_per_domain	Max mailboxes per domain	From plan
aliases_per_mailbox	Max aliases per mailbox	From plan

When a limit is reached, the API returns 403 Forbidden with a clear message:

{
  "detail": "Domain quota exceeded: 5/5"
}

Multiple API Keys

A partner can have multiple active API keys — useful for:

• Giving a DevOps contractor access without sharing the main key
• Rotating keys without downtime (create new, then revoke old)
• Tracking usage per integration

All keys for the same partner share the same quotas and see the same resources.

Example Request

curl -X GET https://api.emboux.com/domains/ \
  -H "Authorization: Bearer emb_k7f2a9x..."

Error Responses

Status	Meaning
403 — Invalid authorization header format	Missing Bearer prefix
403 — Invalid API key	Token doesn’t exist
403 — API key is deactivated	Token was revoked
403 — API key has expired	Token’s expiration date has passed
403 — Domain quota exceeded	Limit reached