API Tokens

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

Click your profile icon in the bottom left corner of the Ankra dashboard.
In the menu, select Profile.
On your profile page, choose API Tokens.
Click Create on the token list page.
Give your token a descriptive name and, if an MCP client will use it, choose its MCP access.
Copy the generated token and store it securely. You will not be able to view it again!

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 the profile page, which is what you want in a script or a fresh CI runner.

# A REST token for the CLI, the API and CI
ankra tokens create ci-deploy

# A token an MCP client may use, read-only or read-write
ankra tokens create cursor --scopes mcp:read
ankra tokens create cursor --scopes mcp:read,mcp:write

# List, then retire one
ankra tokens list
ankra tokens revoke <token-id>
ankra tokens delete <token-id>

The secret is printed once, at creation. -o json writes the whole answer - id, token, type, expiry - for a script to capture:

ankra tokens create ci-deploy -o json > token.json

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 every /api/v1 call your role permits. --scopes adds access to the MCP server, and is the only place scopes apply today.

Scopes	What it can do
(omitted)	The REST API and the CLI, bounded by your organisation role
`mcp:read`	The MCP server’s read-only tools
`mcp:read,mcp:write`	The MCP server’s tools including the ones that change state

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 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.

Credential	Created by	Rotate it with
API token	You, here	`ankra tokens revoke` + `create`
Application registry robot	Ankra, per application	`ankra application registry robot rotate` - see Harbor as your application registry
Cluster agent token	Ankra, when a cluster is created or imported	Reinstalling the agent with a new install command from the cluster’s Settings → General (Generate command)

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:

export ANKRA_API_TOKEN="<your-token>"

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):

env:
  ANKRA_API_TOKEN: ${{ secrets.ANKRA_API_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:

import requests
headers = {"Authorization": "Bearer <your-token>"}
response = requests.get("https://platform.ankra.app/api/v1/clusters", headers=headers)
print(response.json())

Node.js Example:

const res = await fetch("https://platform.ankra.app/api/v1/clusters", {
  headers: { Authorization: "Bearer <your-token>" }
});
console.log(await res.json());

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

Get Started

Concepts

Create and Run Clusters

Ship Your App

Stacks and Add-ons

Observe and Troubleshoot

Ankra AI

Connect Tools

Source Control

Security and Access

Cost and Backups

Organisation and Account

Reference

How to Generate an API Token

Creating a token from the CLI

Scopes

Tokens Ankra creates for you

Use Cases for API Tokens

1. Ankra CLI Authentication

2. CI/CD Integration

3. Programmatic Access (Source Code)

Troubleshooting

More Information

​How to Generate an API Token

​Creating a token from the CLI

​Scopes

​Tokens Ankra creates for you

​Use Cases for API Tokens

​1. Ankra CLI Authentication

​2. CI/CD Integration

​3. Programmatic Access (Source Code)

​Troubleshooting

​More Information

How to Generate an API Token

Creating a token from the CLI

Scopes

Tokens Ankra creates for you

Use Cases for API Tokens

1. Ankra CLI Authentication

2. CI/CD Integration

3. Programmatic Access (Source Code)

Troubleshooting

More Information