Skip to main content

API Keys

API Keys are intended for service-to-service and automation use cases.

Unlike user-level tokens, API Keys are not tied to a logged-in user. They are long-lived credentials designed for backend integrations, scripts, and automated workflows that need stable, unattended access to the PBXware API.

Permission Groups​

Before creating an API Key, you must define a Permission Group. A Permission Group is a named set of scopes that declares exactly what the API Key is allowed to do. Every API Key must have exactly one Permission Group assigned to it. When creating permission group you can select if that group has access to one single tenant, to multiple tenants or it has access to all tenants. Later when you assign permission group to some API Key that API Key will have limited access to tenant(s) defined on permission group.

Permission Groups contain two categories of scopes:

Tenant Scopes (Scopes in Contact Center edition)​

Tenant Scopes cover resources that are managed within a tenant context — things like extensions, contacts, queues, and other per-tenant configuration. In Multi-Tenant Mode these are called Tenant Scopes. In Contact Center Mode, where the instance represents a single logical environment, they are simply called Scopes.

System Scopes​

System Scopes cover resources that belong to the system as a whole, outside of any individual tenant. Examples include:

  • GET /api/v2/system/version — retrieving the PBXware version
  • Tenant package management — creating or modifying tenant packages

If your integration needs to work across tenants or interact with system-level configuration, the relevant System Scopes must be included in the Permission Group.

Creating an API Key​

Once you have a Permission Group ready, you can create an API Key. During creation you will:

  1. Assign a Permission Group — this defines what the key is allowed to do.
  2. Select which tenants the key can access — in Multi-Tenant Mode this controls the scope of cross-tenant operations.
Copy your key immediately

The API Key is shown only once at the time of creation. Copy and store it securely before closing the dialog — it cannot be retrieved afterwards.

Using an API Key​

API Keys are passed in the Authorization header as a Bearer token, the same way user-level access tokens are used:

Authorization: Bearer {your_api_key}

There is no login or token refresh step — the API Key itself is the credential. As long as the key is active and the request falls within the scopes of its Permission Group, the call will be authorized.