REST API
The Axoniq Platform REST API lets scripts and pipelines manage a workspace without the UI: list environments and create or delete them, issue and revoke access tokens, download an environment’s license, and list users and projects.
It uses the same access tokens as the rest of the Platform, with a separate kind of scope for API access.
The interactive reference, with every endpoint, request body and response, is the Swagger UI at https://platform.axoniq.io/api/swagger-ui/index.html. The raw OpenAPI document is at https://platform.axoniq.io/api/v3/api-docs, which you can feed to a client generator.
Getting a token
Open Workspace Settings from the workspace switcher and click Manage access tokens on the Access Tokens card. Click Issue token, tick API access, and choose what the token may do. Each row of API access is one grant, made of a Resource and a Role. Click Add grant for more rows, for example Workspace as Viewer together with Environment as Admin. Only workspace admins and owners can issue tokens.
- Resource
-
Workspace covers the workspace and, at the same role, every environment inside it. Environment covers the environments you select for the token, or all of them if you choose All environments, and nothing at workspace level.
- Role
-
Viewer, Developer or Admin. Each role can do everything the roles before it can. The UI does not offer the owner role, and no API operation needs it.
A token can only be issued with a role you hold yourself. The secret is shown once, unless you chose a reveal type that lets you reveal it later; see Access Tokens.
In the scope names that the API documentation uses, the grant Environment as Admin is api:environment:admin, and Developer is written as user: api:workspace:user.
Calling the API
Send the token as a bearer credential, prefixed by the ID of your workspace:
curl https://platform.axoniq.io/api/v1/environments \
-H "Authorization: Bearer <workspace-id>:<secret>"The workspace ID is part of the credential, so no endpoint takes it as a parameter.
You find the ID of your workspace in the address of any workspace page: https://platform.axoniq.io/workspace/<workspace-id>/…;.
Responses are JSON.
Treat the token like a password. Keep it in your CI system’s secret store, not in source control, and prefer an expiry date over a token that never ends.
What each endpoint needs
Every operation states the role it needs. A token needs that role on the resource named below, directly or through a Workspace grant.
| Operation | Needs |
|---|---|
List environments, users or projects |
Workspace, Viewer |
List a workspace’s access tokens |
Workspace, Viewer |
Reveal an access token’s secret |
Workspace, Developer, and the token’s reveal type must allow it: an Admin for tokens revealable by admins, a Developer or higher for those revealable by members. You also cannot reveal a token that grants a higher role than your own, and a token that is not revealable is never revealed. |
Issue, rename or revoke an access token |
Workspace, Admin |
Create an environment |
Workspace, Admin |
List an environment’s nodes, download its license |
Environment, Viewer |
Remove an offline node from an environment |
Environment, Developer |
Delete an environment |
Environment, Admin |
A token with only an Environment grant cannot call the workspace-level operations, such as listing the workspace’s environments.
A license is a secret, so the API sends Cache-Control: no-store, which tells clients and proxies not to store it.
Errors
| Status | Meaning |
|---|---|
|
The request was rejected: an unknown scope or license version ( |
|
The token is missing or invalid, or does not give the role the operation needs. An environment ID that does not exist, or that belongs to another workspace, also answers |
|
The Platform did not answer in time, or the call behind it failed. Creating an environment is not idempotent: after one of these, list the environments before you retry. |