Authentication

akenza supports two credential types for machine-to-machine access: API keys and OAuth2 Clients. Both use the same permission model: credentials are scoped to an organization, optionally restricted to specific workspaces, and carry a fine-grained set of permissions.

API Keys are passed via x-api-key header to authenticate requests. Choose API Keys when your organization favors simplicity and does not have any requirements regarding short-lived credentials or secret rotation.

OAuth2 Clients authenticate with the industry-standard OAuth2 client credentials grant (OpenID Connect): your application exchanges a client ID and client secret for a short-lived access token and sends it as a standard bearer token. Choose OAuth2 clients when your organization requires standard OAuth2 tooling, short-lived credentials, or secret rotation.

Which credential type should I use?

	API keys	OAuth2 Clients
Authentication	Static secret in the x-api-key header	Short-lived bearer token from the OAuth2 client credentials grant
Token lifetime	n/a (key is long-lived)	15 minutes
Secret rotation	Delete & recreate the key	Rotate the client secret in place
Tooling	Any HTTP client	Any OAuth2/OIDC client library
Permission model	identical	identical

API Keys

Creating a API Keys

API-keys can be found under the API-key menu entry. They can only be created and viewed by Organization Owners and Organization Administrators. Other Members of the Organization have no access to API-keys.

API-keys with assigned permissions

Calling the API

Send the api key as a static secret in the x-api-key header:

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

Do not combine authentication methods: a request carrying both an Authorization header and an x-api-key header is rejected.

OAuth2 Clients

Creating an OAuth2 Client

OAuth2 clients are managed at the organization level and require organization manage permission.

Via the Console (TBA)

Via the REST API (authenticated as a user)

POST https://api.akenza.io/v3/oauth-clients

{
  "name": "data-poller",
  "description": "Client for data polling",
  "organizationId": "0123456789abcdef",
  "allWorkspaces": true,
  "permissions": {
    "asset": [
      "read"
    ]
  }
}

To restrict the client to specific workspaces, set "allWorkspaces": false and list the workspaces:

{
  "allWorkspaces": false,
  "workspaces": [
    {
      "id": "fedcba9876543210"
    }
  ]
}

The response contains the credentials:

{
  "id": "1a2b3c4d5e6f7a8b",
  "name": "data-poller",
  "organizationId": "0123456789abcdef",
  "clientId": "3fa1b2c3d4e5f6a7",
  "clientSecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "tokenUrl": "https://login.akenza.io/realms/api-keys/protocol/openid-connect/token",
  "permissions": {
    "...": "..."
  }
}

Store the clientSecret in a secret manager it will not be available later.

Requesting an access token

Request tokens from the akenza token endpoint using the client credentials grant:

Environment	Token endpoint
Production	https://login.akenza.io/realms/api-keys/protocol/openid-connect/token

curl -s -X POST 'https://login.akenza.io/realms/api-keys/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'client_secret=YOUR_CLIENT_SECRET'

HTTP Basic authentication (-u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET) is supported as well.

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 900,
  "token_type": "Bearer"
}

Tokens are valid for 15 minutes; there are no refresh tokens. Request a new token when the current one is about to expire. Cache the token and reuse it across API calls; do not request a new token per request.

akenza publishes standard OpenID Connect discovery metadata at https://login.akenza.io/realms/api-keys/.well-known/openid-configuration, so most OAuth2 client libraries can be configured with the discovery URL alone.

Calling the API

Send the token as a bearer token in the Authorization header:

curl -s 'https://api.akenza.io/v3/assets' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'

Do not combine authentication methods: a request carrying both an Authorization header and an x-api-key header is rejected.

Managing OAuth2 Clients

Action	Request
List clients	GET /v3/oauth-clients?organizationId={orgId}
Get a client	GET /v3/oauth-clients/{id}
Rotate the secret	POST /v3/oauth-clients/{id}/rotate-secret
Delete a client	DELETE /v3/oauth-clients/{id}

Rotation: the old secret stops working immediately; tokens that were already issued remain valid until they expire (at most 15 minutes). Rotate during a maintenance window or update your deployment with the new secret right away.

Deletion: the client can no longer obtain tokens, and already-issued tokens are rejected within about one minute.

Permissions

Both OAuth2 Clients and API keys use the same permission model. Each entry in permissions maps a scope to a list of verbs (create, read, update, delete, manage):

• organization (read is always granted)

• organization.member

• workspace

• workspace.member

• asset

• deviceType

• dataFlow

• integration

• rule

• customLogic

• deviceCredential

• dashboard

• dashboard.group

• billing

• blob

• dataFusionLayer

Scopes containing a dot must be quoted as JSON keys, e.g. "workspace.member": ["read"].

Troubleshooting

Symptom	Cause & fix
401 invalid token when calling the API	The token expired, or the client was deleted. Request a new token.
401 Two authentication headers received	The request carries both Authorization and x-api-key. Send exactly one.
401 invalid_client from the token endpoint	Wrong client_id/client_secret
403 permission denied on an API call	The client lacks the required scope/verb or workspace - check its permissions.