API Keys

Note

API key management endpoints require the master token. Client tokens cannot create or modify API keys.

Create API Key

POST /api-keys/

Request Body

Field	Type	Required	Default	Description
token	string	Yes	—	The key value (generate securely)
partner_ref	string	Yes	—	Partner identifier
domains_allowed	integer	No	0	Domain limit (0 = unlimited)
mailboxes_per_domain	integer	No	1	Mailboxes per domain
aliases_per_mailbox	integer	No	5	Aliases per mailbox
active	boolean	No	true	Whether the key is active
expires_at	string	No	null	ISO 8601 expiration date. null = never expires

Example

curl -X POST https://api.emboux.com/api-keys/ \
  -H "Authorization: Bearer MASTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "emb_k7f2a9xP3mN...",
    "partner_ref": "partner_42",
    "domains_allowed": 10,
    "mailboxes_per_domain": 5,
    "aliases_per_mailbox": 20,
    "expires_at": "2026-12-31T23:59:59"
  }'

Response 201 Created

{
  "id": 1,
  "token": "emb_k7f2a9xP3mN...",
  "partner_ref": "partner_42",
  "domains_allowed": 10,
  "domains_used": 0,
  "mailboxes_per_domain": 5,
  "aliases_per_mailbox": 20,
  "active": true,
  "expires_at": "2026-12-31T23:59:59",
  "created_at": "2025-01-15T10:00:00",
  "last_used_at": null
}

---

Update API Key

PUT /api-keys/{token}

Update quotas or deactivate a key. Only provided fields are changed.

Request Body

Field	Type	Description
domains_allowed	integer	New domain limit
mailboxes_per_domain	integer	New mailbox limit
aliases_per_mailbox	integer	New alias limit
active	boolean	Activate or deactivate
expires_at	string	New expiration date (null to remove)

Example

curl -X PUT https://api.emboux.com/api-keys/emb_k7f2a9xP3mN... \
  -H "Authorization: Bearer MASTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domains_allowed": 20, "active": true}'

---

Delete API Key

DELETE /api-keys/{token}

Permanently removes the key. Resources created with this key remain but become inaccessible.

curl -X DELETE https://api.emboux.com/api-keys/emb_k7f2a9xP3mN... \
  -H "Authorization: Bearer MASTER_TOKEN"

Response 204 No Content

---

Get Usage

GET /api-keys/{token}/usage?since={ISO_datetime}

Returns resources created by this key, optionally filtered by date.

Query Parameters

Parameter	Type	Required	Description
since	string	No	ISO 8601 datetime. Only return resources created after this date.

Example

curl "https://api.emboux.com/api-keys/emb_k7f2a9xP3mN.../usage?since=2025-01-01T00:00:00" \
  -H "Authorization: Bearer MASTER_TOKEN"

Response 200 OK

{
  "domains_allowed": 10,
  "domains_used": 3,
  "mailboxes_per_domain": 5,
  "aliases_per_mailbox": 20,
  "domains_created_since": [
    {"name": "example.com", "created_at": "2025-01-10T08:00:00"}
  ],
  "mailboxes_created_since": [
    {"email": "user@example.com", "domain_name": "example.com", "created_at": "2025-01-10T08:05:00"}
  ],
  "aliases_created_since": []
}

---

Multiple Keys Per Partner

A partner can have multiple active API keys. All keys for the same partner:

• Share the same quota pool (domain count, etc.)
• See the same resources
• Are independently revocable

This is useful for giving different teams or contractors separate keys for auditing and access control.