How to Generate an API Token
The portal offers Create token only once your account has two-step sign-in. Without it, the page asks you to “Add a second step to sign in first”; see Account Security & 2FA.- Open Your account from the account menu, then API access (
/next/account/api). - Under Your tokens, click Create token.
- In Create a token, give it a Name, choose What can it do? (Full API access for the CLI, the REST API and CI; Editor tools: read and change or Editor tools: read only for an MCP client), and pick Expires after: 7 days, 30 days, 90 days (the default) or 1 year.
- Click Create token. The dialog becomes Copy your token now: “This is the only time Ankra shows it.” Copy the token and store it securely.
- Check that the token is listed under Your tokens.
Creating a token from the CLI
ankra tokens manages the same tokens as API access, which is what you want in a script or a fresh CI runner.
-o json writes the whole answer - id, token, type, expiry - for a script to capture:
Scopes
A token created without--scopes is a REST token: it authenticates the CLI and the /api/v1 calls your role permits, with two exceptions. A read that has no /api/v1 route of its own is served from the portal’s route only to a personal token with no scopes and no project pin (see Base URL), and a token pinned to a project is refused organisation-wide routes such as the organisation’s settings, billing changes and the audit log, with 403 and Pinned tokens cannot act outside their project. --scopes makes it an MCP token instead: it reaches the MCP server and is refused by every other /api/v1 route. Scopes apply nowhere else.
An MCP-scoped token is bound to the organisation it was created in and refuses to act anywhere else: passing
--org (or X-Ankra-Organisation-Id) with one is rejected rather than honoured. Create one token per organisation you want an MCP client to reach. A REST token accepts the override as usual.A token minted with a project is pinned to it as well. An MCP-scoped token created in the console is pinned to the project chosen in the create dialog, which defaults to the project you are working in, and --project <name> pins any token from the CLI. A pinned token acts in that project only: X-Ankra-Project-Id naming another project is refused, and the token stops authenticating if its project is deleted. A REST token created without --project acts in the organisation’s Default project, or in the oldest project a project-only member reaches, and may name another project of the same organisation with X-Ankra-Project-Id. It never follows the project selected in the console. Tokens created before projects were released carry no pin. The token list says which project each token acts in.Tokens Ankra creates for you
Not every credential in the platform is one of these tokens, and the distinction matters when you are rotating something.
Ankra-managed credentials appear in your organisation’s credential lists marked as managed; they cannot be edited there, only through the resource that owns them.
Use Cases for API Tokens
1. Ankra CLI Authentication
Set theANKRA_API_TOKEN environment variable to authenticate the CLI:
2. CI/CD Integration
Use API tokens in your CI/CD pipelines to automate cluster management, addon deployment, or other Ankra API operations. Store tokens as secrets in your CI/CD system (e.g., GitHub Actions, GitLab CI, Jenkins). Example (GitHub Actions):3. Programmatic Access (Source Code)
API tokens can be used in scripts or applications written in any language that supports HTTP requests (e.g., Python, Go, Node.js, Bash). Python Example:Troubleshooting
- Token not working? Double-check you copied it correctly and that it has the right permissions.
- Lost your token? Revoke it, create a new one, then delete the old row.
- Permission errors? A personal token acts with its owner’s role and a service token with the role it was given; an MCP client also needs the matching
mcp:scope.
More Information
- API Reference - authenticate and call every Ankra endpoint
- Ankra CLI - token-based login for terminal and CI use
- Contact Support