API keys

Issue credentials for the akenza APIs, restrict them to specific workspaces, and grant only the permissions they need.

An API key is a static secret that lets an application reach akenza without a user account. It is sent in the x-api-key header on every request, and the REST API, the WebSocket API, and integrations such as the Grafana data source all authenticate this way.

Keys belong to the organization and are managed under Settings > API Keys.

API keys are one of two credential types. OAuth2 clients are the other, and they carry the same scope and permission model.

Who can manage API keys

Only the organization owner and organization admins can create and view API keys. For everyone else the API credential management is not available at all, which means a key never exposes more than the people who could already administer the organization.

Creating an API key

1

Open the creation form

Select Create API Key on the API Keys page.

2

Name it

Give the key a name and, optionally, a description. Name it after the system that will use it, for example Grafana or Data Consumer, and use the description to record what it is for. Both are shown in the list, and they are the only way to tell later which key belongs to which integration.

3

Choose the scope

By default a key reaches every workspace in the organization, including workspaces created later. Enable Restrict permissions to specific Workspaces and select the workspaces it may reach to narrow that down.

4

Select the permissions

Under Permissions, expand a group and tick the individual verbs it may use. All permissions selects everything at once, which is worth avoiding for anything but a throwaway key.

Each permission group expands into the verbs the key may use

5

Create and store the secret

Select Create API key. Copy the generated secret into your password manager or secret store before you leave the page, and configure it in the application that needs it.

Permissions

Permissions are granted per group and per verb. The groups cover organization users, billing, workspaces and workspace users, devices, device types, data flows, integrations, rules, custom logic, dashboards, and the Data Fusion Layer. Depending on the group, the available verbs are create, read, update, delete, and manage.

Organization read is always granted and cannot be removed, because a key has to be able to resolve the organization it belongs to. Everything beyond that is off until you grant it.

Grant the smallest set that does the job. A key that only feeds a reporting tool needs asset: read and nothing else, while a key with manage on workspace members can change who has access to your data. Keys do not expire, so an over-permissioned key stays over-permissioned until someone notices.

The permission names shown when you open a key are the same scope names used by the API, such as asset, dataFlow, workspace.member, and organization.member. See Authentication for the full list and for how they map onto requests.

Viewing, copying, and deleting a key

Selecting a key's name opens a panel with everything it can do:

• The API key itself.

• Its permissions, listed as scope and verbs, for example organization: read and asset: all.

• Its scope, the organization and either All workspaces or the workspaces it was restricted to.

Copy in the list row copies the key. Delete revokes it immediately, and any application still using it starts receiving 401 responses, so check what the key is wired into before removing it.

A key's permissions and scope cannot be edited after creation. To change what a key may do, create a replacement, move your integrations across to it, and then delete the old one.

Using the key

Send the secret in the x-api-key header:

curl -s 'https://api.akenza.io/v3/assets' \
  -H 'x-api-key: 099123122.2ab1000..'

A request that carries both an Authorization header and an x-api-key header is rejected, so send exactly one. If a call returns 403 permission denied, the key is missing either the scope and verb for that endpoint or access to the workspace the object lives in.

Actions taken with an API key appear in the audit logs alongside actions taken by users, which is another reason to give each integration a key of its own rather than sharing one.

OAuth2 clients

An OAuth2 client is the second credential type for machine-to-machine access. Instead of sending a long-lived secret on every request, your application exchanges a client ID and client secret for an access token using the OAuth2 client credentials grant, then sends that token as a standard bearer token. Tokens are valid for 15 minutes and there are no refresh tokens.

Both credential types are issued per organization, can be restricted to specific workspaces, and use the same permissions, so the choice is about how the credential is handled rather than about what it may do:

	API keys	OAuth2 clients
Sent as	A static secret in the x-api-key header	A short-lived bearer token in the Authorization header
Lifetime	Long-lived until deleted	15 minutes per token
Rotation	Delete and recreate the key	Rotate the client secret in place
Tooling	Any HTTP client	Any OAuth2 or OpenID Connect client library
Permission model	Identical

Choose API keys when simplicity matters and you have no requirement for short-lived credentials or secret rotation. Choose OAuth2 clients when your organization expects standard OAuth2 tooling, wants credentials that expire on their own, or needs to rotate a secret without a gap in service, since rotation keeps already-issued tokens working until they expire.

Authentication