API Keys

API keys let your own software, integrations and AI agents call the Zingasuite API on your behalf. Every key is a bearer token that begins with zk_ and acts as the member who created it, in one specific entity.

Two places to manage keys

Entity keys — under Settings → API Keys for an entity. These are the keys you own within that workspace, ideal for integrations that belong to the business.
Personal keys — under your personal Settings → API Keys, which lists every key you own across all your entities in one place.

You only ever see and manage keys you created — you can never view another member's keys or their tokens.

Creating a key requires the Create & manage API keys capability (owners and admins have it by default).

Creating a key

When you create a key you choose:

Name — a label so you can recognise it later (for example, "Warehouse sync").
Key type — ai_agent, integration, or personal. This is a descriptive tag for how the key is used.
Environment — live or test. Live keys begin with zk_live_; test keys begin with zk_test_.
Scopes — what the key is allowed to do (see below).
Expiry (optional) — a number of days after which the key automatically stops working. Leave it empty for a key that never expires.

The token is shown once

When the key is created, the full secret token is displayed exactly once. Copy it and store it somewhere safe immediately — Zingasuite keeps only a hashed form and can never show or recover the plaintext again. If you lose it, revoke the key and create a new one.

Scopes

Scopes narrow what a key can do. You can grant any combination of the following:

Scope	Grants
`data:read`	Read access to your app data (catalog, orders, inventory, contacts, and so on).
`data:write:*`	Write access (create / update / delete) across all data object types.
`billing:read`	Read access to billing information such as the AI Token balance.
`messaging:read`	Read messaging data (conversations and message status) in ZingaConnect.
`messaging:send`	Send messages through ZingaConnect.
`messaging:webhooks`	Manage the delivery webhooks for messaging integrations.

Notes on how scopes behave:

Messaging is separate from data. data:write:* does not grant any messaging ability, and messaging scopes grant no access to catalog or order data. This lets you issue a key that can only send messages, with no reach into the rest of your business.
Scopes are a ceiling, not a grant. A key can never do more than the member who created it. At request time the key's scopes are intersected with that member's own permissions. See Roles & Permissions.
Administrative and platform-wide scopes cannot be granted to tenant keys.

Using a key

Send the token as a bearer credential against the public API base:

https://api-v1.zingasuite.com/papi/v1

Authorization: Bearer zk_live_xxxxxxxxxxxxxxxxxxxxxxxx

For the full list of endpoints, request and response shapes, and worked examples, see the Developer API Reference.

Revoking a key

You can revoke any key you own at any time from the same page. Revocation takes effect immediately and cannot be undone — the token stops authenticating on its next use. Revoke a key whenever it is no longer needed, may have leaked, or belonged to a decommissioned integration. To rotate a key, create a new one, switch your integration over, then revoke the old one.

Each key also records when it was last used, which helps you spot keys that are safe to retire.