Skip to content

API Keys

API Keys allow external applications and integrations to call AKAS REST endpoints using header-based authentication (X-API-Key and X-API-Secret). Access is controlled by the same permission scopes used for interactive users (for example invoice.list).

API keys are managed through the left sidebar → Security menu → API Keys (/security/apiKeys). Managing keys requires the apikey permission scope (list, view, create, update, delete).

  1. When you create an API key, AKAS generates a key and a secret, and automatically creates a dedicated paired role for that key (one key = one role).
  2. You assign permissions to that key from the API Keys list (same permission matrix used for roles).
  3. External clients send the key and secret on each request. AKAS authenticates the key and enforces the assigned scopes on every protected endpoint.
  4. The paired role is not shown on the Roles list and cannot be assigned to interactive users. Manage its permissions only from API Keys.
  1. Open Security → API Keys.
  2. Click Create.
  3. Enter a name (remark) to identify the key (for example, “POS integration” or “Reporting bot”).
  4. Click confirm. AKAS shows the API Key and API Secret once.

Important: Copy and store the key and secret immediately. The secret is shown only at creation time and cannot be retrieved again.

The list shows each key’s identifier (masked), disabled status, and remark. Available actions:

Action Description
Edit Update the remark or disable/enable the key.
Permissions Open the permission matrix for this key’s paired role. Grant only the scopes the integration needs (for example invoice.list).
Delete Remove the key and its paired role. Existing clients using that key will stop working.

Disabling a key keeps it in the list but rejects authentication until it is enabled again.

Send the key and secret on every request:

GET /api/Invoices HTTP/1.1
Host: your-akas-host
Accept: application/json
X-API-Key: <your-api-key>
X-API-Secret: <your-api-secret>

Example with curl:

Terminal window
curl --url 'https://your-akas-host/api/Invoices' \
-H 'Accept: application/json' \
-H 'X-API-Key: <your-api-key>' \
-H 'X-API-Secret: <your-api-secret>'

If your deployment uses tenants, also send the tenant identifier:

X-Tenant-Id: <tenant-identifier>

Without a valid tenant header, the key may not be found and the request returns 401 Unauthorized.

API key headers are already allowed (AllowAnyHeader). For calls from a browser (for example the marketing site contact form), the page origin must be allowed by the system setting CORS (comma-separated suffixes; matched with EndsWith). Manage it under System Settings. On first startup, values are copied once from appsettings Cors if the setting is missing. Server-to-server / curl calls are not subject to CORS.

After authentication, AKAS applies the same [Authorize("scope.action")] checks as for browser users. If the key’s permissions do not include the required scope (for example invoice.list), the request is denied even when the key and secret are valid.

  • Create a separate key per integration so you can revoke or limit one without affecting others.
  • Grant least privilege — only the scopes that integration needs.
  • Store secrets in a secure vault; never commit them to source control or share them in chat.
  • Disable or delete keys that are no longer used.
  • Rotate by creating a new key, updating the client, then deleting the old key.

Users — Interactive login accounts

Roles — Named permission groups for users (API key roles are managed separately)

Permissions — Permission matrix and action types