Skip to main content
API tokens are secure credentials that allow you to authenticate and interact with the Ankra platform programmatically. They are used for CLI operations, CI/CD automation, and integrating Ankra with your own tools or scripts.

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.
  1. Open Your account from the account menu, then API access (/next/account/api).
  2. Under Your tokens, click Create token.
  3. 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.
  4. 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.
  5. Check that the token is listed under Your tokens.
A token near its expiry date appears under Needs you on the same page. Renew creates a new token with the same name, access and lifetime, and the current token keeps working for up to 24 hours, or until its own expiry if that comes first, so you have time to switch. Revoke stops a token at once. To connect Claude Code or Cursor, use Connect your editor on the same page. Claude Code needs no token: it signs in to Ankra the first time it uses a tool.
For security, create separate tokens for different use cases (e.g., CLI, CI/CD, integrations). A personal token acts as you; for automation that runs without a person behind it, create a service token with the narrowest role that does the job.

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.
The secret is printed once, at creation. -o json writes the whole answer - id, token, type, expiry - for a script to capture:
Revoking and deleting are two steps, and only revoking stops the token working. ankra tokens delete refuses a token that is still live: revoke it first, then delete it to remove the row. A revoked token is dead immediately, whatever it is stored in.

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.
A token never exceeds the role of the person who created it - roles and scopes decide what it may do, and a token created by a viewer stays read-only however it is used.

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 the ANKRA_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):
A GitHub Actions workflow can also sign in with no stored token at all, through a trust policy on the repository. See GitHub Actions without a stored token.

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:
Node.js 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