Authentication

The Ziett API uses API Keys for authentication. Every request your application makes to the Ziett API must include a valid API Key in the request headers. There are no session tokens, cookies, or OAuth flows for server-to-server integrations.

Your API Key

API Keys are generated per Organization and can be managed from the Ziett Dashboard under Organizations → API Keys.

Each key is:

• Unique — tied to a single Organization.
• Scoped — carries a set of permissions (e.g., messages:send, campaigns:read) that define what operations it can perform.
• Revocable — can be rotated or deleted at any time from the Dashboard without affecting other keys.

Making Authenticated Requests

Include your API Key in the X-API-KEY HTTP header with every request:

POST /c/v1/messages HTTP/1.1
Host: api.ziett.co
Content-Type: application/json
X-API-KEY: zk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl -X GET https://api.ziett.co/c/v1/messages/019b4b56-e704-7c30-83a0-527df63c3e00 \
  -H "Accept: application/json" \
  -H "X-API-KEY: zk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

API Key Environments

Ziett issues keys with a prefix that indicates the environment:

Always use your test key during development and integration testing. Switch to your live key only when you are ready to go to production.

Note: Not all channels support test environments.

Key Scopes

When creating an API Key, you assign it one or more scopes that define the exact operations it is permitted to perform. Requesting an operation outside the key's scopes results in a 403 Forbidden error. Below are some examples.

Principle of Least Privilege: Create dedicated API Keys for each of your services or microservices, and assign only the scopes that service actually needs. A key used exclusively by a notification service does not need campaigns:send access.

Security Best Practices

Your API Key is a secret credential. Treat it with the same level of care as a database password.

Never expose your key in client-side code. Keys embedded in frontend JavaScript, mobile apps, or public web pages can be extracted by anyone. All Ziett API calls must originate from your backend servers.

Never commit keys to version control. Use environment variables or a secrets manager (e.g., Cloud Secret Manager, AWS Secrets Manager, HashiCorp Vault, or a .env file excluded via .gitignore) to inject keys at runtime.

Rotate keys regularly. You can generate a new key from the Dashboard and deprecate the old one without any downtime. We recommend rotating keys whenever a team member with access leaves your organization.

Use separate keys per environment. Never use your production key in a staging or development environment. This prevents accidental charges and keeps your production audit logs clean.

Authentication Errors

If a request cannot be authenticated, the API returns a 401 Unauthorized or 403 Forbidden response.

{
  "code": "AUTH_INVALID_API_KEY",
  "message": "The provided API key is invalid or has been revoked.",
  "status": 401,
  "trace_id": "a1b2c3d4e5f644358a9e7011c123c831",
  "timestamp": "2025-07-14T10:30:00.000000+00:00",
  "service": "core"
}

{
  "code": "AUTH_INVALID_SCOPE",
  "message": "Insufficient permissions to perform this action.",
  "status": 403,
  "trace_id": "d309f78ae57744358a9e7011c123c831",
  "timestamp": "2025-07-14T10:30:00.000000+00:00",
  "service": "core",
  "fields": {
    "apikey": "The provided key does not have the 'messages:send' scope."
  }
}

Now that your key is set up, the next step is to understand how to handle errors, rate limits, and retries correctly. Continue to Rate Limits & Reliability.