Skip to main content
You end up with a token that calls the Ankra REST API and a working request that lists your organisation’s clusters. It takes about five minutes.

Before you start

  • An Ankra account in an organisation. The request lists the clusters of the organisation the token is made in.
  • Two-step sign-in on your account, to make the token in the portal. Without it, Create token is missing and Your account → API access shows Add a second step to sign in first. Set it up first: Account security.
  • A shell with curl, or Python or Node.js for the other examples. jq is optional, for reading the answer.

Steps

1

Create a token with Full API access

The token must be a REST token. A token made for editor tools is refused by every REST route, and the portal preselects that kind.
  1. Open Your account → API access (/next/account/api) and select Create token.
  2. In Name, say where the token is used, for example my-first-api-call.
  3. Under What can it do?, select Full API access.
  4. Choose a lifetime under Expires after, then select Create token.
  5. Reveal the token and copy it, tick I have stored it somewhere safe, then select Done. Ankra shows the token only once.
You should see the token under Your tokens reading Full API access with its expiry date, or in ankra tokens list.For CI/CD, Terraform or anything else that runs without you, make a service token instead. It belongs to the organisation and keeps working after you leave it.
2

Put the token in an environment variable

You should see the token’s first characters with echo "${ANKRA_API_TOKEN:0:6}". Keep the token out of files you commit.
3

Make the request

Send the token as a bearer token to GET /api/v1/clusters:
You should see a JSON object with three keys: result, pagination and metrics. An error answers with a JSON body holding detail instead; see What can go wrong.
4

Read the answer

result is the list of clusters. Each one has its id, name, kind, state and environment, among other fields. Print one line per cluster with jq:
pagination says which page you read: page, page_size, total_pages and total_count. The list holds 25 clusters per page unless you pass page_size (at most 100), so read total_pages before you assume you have them all:
You should see the same clusters as under Clusters in the portal. The id is what other cluster endpoints take as cluster_id.

Verify

Print only the HTTP status of the request:
It prints 200.

What can go wrong

Where to go next

  • API introduction: authentication, the organisation and project headers, errors, rate limits and both pagination shapes.
  • The Endpoints pages of the API reference: every operation with its parameters and response shape.
  • Service tokens: a credential for automation that belongs to the organisation.
  • API tokens: every kind of token Ankra issues.