API Keys

Create and manage API keys from the dashboard or via the endpoints below (using an existing API key). Send the key in every request as Authorization: Bearer YOUR_API_KEY. Sandbox keys use prefix zatca_test_, production keys zatca_live_. You can optionally set a default EGS unit on a key so invoice requests can omit egs_unit_id; see Flow & integration. The raw key is returned only once when created.

GET/v1/api-keys

List API keys (masked)

Returns all API keys for the tenant. Keys are masked; only the prefix and last few characters are shown.

Requires API Key (Bearer)

Code examples

const res = await fetch('https://api.esnadapi.com/v1/api-keys', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();

Success response (200)

{
  "data": [
    {
      "id": "uuid",
      "label": "Production POS",
      "key_prefix": "zatca_live_••••••••",
      "default_egs_unit_id": "egs_abc123",
      "created_at": "2025-01-15T10:00:00.000Z",
      "last_used_at": null
    }
  ]
}

POST/v1/api-keys

Create API key

Creates a new API key. The full key is returned only in this response; store it securely.

Requires API Key (Bearer)

Request body

CreateApiKeyDto

Field	Type	Required	Description
label	string	No	Friendly name (e.g. Production POS)
prefix	"zatca_live_" \| "zatca_test_"	No	Default: zatca_test_
default_egs_unit_id	string	No	EGS unit to use when invoice APIs omit egs_unit_id. Must match key env (test→sandbox unit, live→production unit).

Code examples

const res = await fetch('https://api.esnadapi.com/v1/api-keys', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${apiKey}`,
  },
  body: JSON.stringify({ label: 'Production POS', prefix: 'zatca_live_', default_egs_unit_id: 'egs_xxx' }),
});
const { raw_key } = await res.json(); // store raw_key securely - shown only once

Success response (200)

{
  "id": "uuid",
  "raw_key": "zatca_test_xxxxxxxxxxxxxxxxxxxxxxxx",
  "key_prefix": "zatca_test_••••••••",
  "default_egs_unit_id": null,
  "created_at": "2025-01-15T10:00:00.000Z"
}

PATCH/v1/api-keys/:id

Update API key (label and/or default EGS unit)

Update the key's label or default_egs_unit_id. Set default_egs_unit_id to null to clear. The unit must match the key environment (sandbox/production).

Requires API Key (Bearer)

Request body

UpdateApiKeyDto

Field	Type	Required	Description
label	string	No	—
default_egs_unit_id	string \| null	No	EGS unit to use when invoice APIs omit egs_unit_id; null to clear.

Code examples

await fetch(`${BASE}/v1/api-keys/${keyId}`, {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
  body: JSON.stringify({ default_egs_unit_id: 'egs_xxx' }),
});

Success response (200)

{
  "id": "uuid",
  "label": "Production POS",
  "default_egs_unit_id": "egs_abc123"
}

Error responses

404
```
{
  "message": "Key not found"
}
```

DELETE/v1/api-keys/:id

Revoke API key

Permanently revokes an API key. Requests using that key will receive 401.

Requires API Key (Bearer)

Code examples

await fetch(`${BASE}/v1/api-keys/${keyId}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${apiKey}` },
});

Success response (200)

{
  "ok": true
}

Error responses

404

{
  "message": "Key not found or already revoked"
}