API tokens

Overview

An API token opens the /v1 API without a browser login. A CI job, a server that uses an SDK, and a third-party integration use it. You make a token, choose what it reaches and what it can do, and the platform shows the secret once.

A token starts with klt_. The platform stores only a digest of the secret, so a lost token must be revoked and replaced. Only you can list or revoke the tokens that you made.

A token acts as you, inside its limits. It can never do more than you can do. If your role in a team falls, the token falls with it.

Reach

The reach is the owner of the token. You set it when you make the token and cannot change it.

A team that you join later is in the reach of a * token. A team that you leave or that pauses you is not.

Parts and verbs

A token holds verbs. There are nine, in three parts. No verb includes another: a token that can update a pipeline cannot start a run of it.

A kind admits only the verbs that mean something for it. A grant that names another verb is refused with 422.

The kind pipelines is the definitions and their versions. The kind pipeline-runs is the runs of a pipeline, their logs, and the cancel of a run. A selector on pipeline-runs matches the name of the pipeline of the run.

Presets

Set access to a list of parts. The platform expands each part into one grant on every kind in reach, with the verbs of that part that the kind admits. The expansion leaves out delete and exec.

Use any subset, for example ["monitoring", "management"]. In the console, three switches set the parts: Monitoring, Resource management, and Executions. Two ticks, Include delete and Include exec, add destroy and exec.

Send access or grants, never both. The platform stores the expanded grants. Use grants for control of one kind or one resource.

Grants

A grant has a kind, a list of verbs, and a list of resources. It can also have own and, on capsules, limits. A request passes when one grant covers its kind, its verb, and the resource that it names.

A selector matches the id or the name of the resource. The prefix is literal: vendor-* matches vendor-a and not vendors-a. A * inside a selector is not a wildcard.

A route that names a second resource needs a grant for it. An example is a desk that connects to an environment. A missing grant on one of them is a 401.

Only what the token created

With own: true, a grant covers an object only when this token created it. The platform stamps the label k-ode.dev/created-by-token on each workspace, environment, desk, capsule, pipeline, and run that a token makes. Two integrations in one team cannot see or stop the capsules and runs of each other.

A create with no name is permitted when the grant has own, because the token can then touch only what it made. own is refused on volumes and snapshots, which a token never creates.

Limits of executions

A capsules grant that holds run or exec can carry limits. A create that is outside the limits is refused with 401.

The cap of runs in flight, max_live_runs, counts the live capsules and pipeline runs that one token started. The range is 1 to 50 and the default is 5. The next start gets 429 with this token has {n} runs in flight; the limit is {max}. Another run can start when one ends. The cap is a limit on cost for a token that leaks. It is not a rate limit.

Who started a run

A pipeline run or a capsule that a token starts records the token. The record holds apiToken with the name and the first eight characters of the id. The console shows API token {name} and never the handle of the creator.

A manual start of a pipeline takes an optional key. A second start with the same key answers the run that the first start made, so a retry cannot start a duplicate. Each token and each person has its own keys.

Secrets

A token cannot send a request that names a secret. A request is refused with 401 when a string in its body holds ${{ secrets., at any depth, or when a pipeline definition has secrets. A token cannot read a secret value.

A token can start a pipeline that uses a secret, if someone else wrote the pipeline. The pipeline uses the secret. The holder of the token never receives it.

Limits

A token always expires. The list shows the expiry and the time of the last use. The platform records the last use at most once an hour.

What a token cannot do

A token cannot reach the routes for tokens, keys, teams, invitations, secrets, connectors, requests, sign-in, or the console administration. It cannot read a secret value. It cannot open a tool server or an SSH session. exec reaches the attach route of a capsule and no other route. These routes answer 401 missing or invalid token, the same answer as a wrong token.

A request for a resource outside the grants is the same 401. A request with ?owner= or team for a team that a one-team token does not serve is 403 with this token acts only for and the team.

How lists are narrowed

A list route answers only the items that the grants select. A grant with * and no own returns the whole page. A grant with selectors or own removes the other items from the page, so a page can be short or empty while more pages follow. Follow the x-next-cursor header until it is absent.

Tasks

Create an API token

Reason for the task

Give a program read access, and the right to manage resources, in one owner.

Job set-up

• Access: you, signed in with the console or a CLI login. A token cannot make a token. A team token needs an active team member.
• References: POST /v1/tokens.

Procedure

1. Create the token with name, owner, and access. In the console, select New token in Profile settings.

   PythonCopy

   t = kl.request("POST", "/v1/tokens", body={    "name": "ci",    "owner": "acme",    "access": ["monitoring", "management"]})

   TypeScriptCopy

   const t = (await kl.request("POST", "/v1/tokens", {  name: "ci",  owner: "acme",  access: ["monitoring", "management"]})) as { _id: string; token: string };

   GoCopy

   var t map[string]anyerr := kl.Request("POST", "/v1/tokens", kloudlite.RequestOptions{    Body: map[string]any{        "name": "ci",        "owner": "acme",        "access": []string{"monitoring", "management"},    },    Out:  &t,})if err != nil {    log.Fatal(err)}

   RubyCopy

   t = kl.request("POST", "/v1/tokens", body: {  name: "ci",  owner: "acme",  access: ["monitoring", "management"]})

   JavaCopy

   String t = kl.request(new Kloudlite.RawRequest().method("POST").path("/v1/tokens")    .body("{\"name\":\"ci\",\"owner\":\"acme\",\"access\":[\"monitoring\",\"management\"]}"));

   CLICopy

   kode request POST /v1/tokens --body '{"name": "ci", "owner": "acme", "access": ["monitoring", "management"]}'

2. Put the token value in your secret store. The platform does not show it again.

Close-out

1. Show the tokens as in task 10-20-00-005. Make sure that the new token is listed.

Create a token that runs one pipeline

Reason for the task

Give a vendor the right to run the pipeline nightly-report and to read its runs and logs, and nothing else.

Job set-up

• Access: you. The owner is a team where you are an active member.
• References: POST /v1/tokens.

Procedure

1. Create the token with one grant on pipeline-runs for read, logs, and run. Set two runs in flight and 30 days.

   PythonCopy

   t = kl.request("POST", "/v1/tokens", body={    "name": "vendor-report",    "owner": "acme",    "expires_in_days": 30,    "max_live_runs": 2,    "grants": [        {            "kind": "pipeline-runs",            "verbs": ["read", "logs", "run"],            "resources": ["nightly-report"]        }    ]})

   TypeScriptCopy

   const t = (await kl.request("POST", "/v1/tokens", {  name: "vendor-report",  owner: "acme",  expires_in_days: 30,  max_live_runs: 2,  grants: [    {      kind: "pipeline-runs",      verbs: ["read", "logs", "run"],      resources: ["nightly-report"]    }  ]})) as { _id: string; token: string };

   GoCopy

   var t map[string]anyerr := kl.Request("POST", "/v1/tokens", kloudlite.RequestOptions{    Body: map[string]any{        "name": "vendor-report",        "owner": "acme",        "expires_in_days": 30,        "max_live_runs": 2,        "grants": []map[string]any{            {                "kind": "pipeline-runs",                "verbs": []string{"read", "logs", "run"},                "resources": []string{"nightly-report"},            },        },    },    Out:  &t,})if err != nil {    log.Fatal(err)}

   RubyCopy

   t = kl.request("POST", "/v1/tokens", body: {  name: "vendor-report",  owner: "acme",  expires_in_days: 30,  max_live_runs: 2,  grants: [    {      kind: "pipeline-runs",      verbs: ["read", "logs", "run"],      resources: ["nightly-report"]    }  ]})

   JavaCopy

   String t = kl.request(new Kloudlite.RawRequest().method("POST").path("/v1/tokens")    .body("{\"name\":\"vendor-report\",\"owner\":\"acme\",\"expires_in_days\":30,\"max_live_runs\":2,\"grants\":[{\"kind\":\"pipeline-runs\",\"verbs\":[\"read\",\"logs\",\"run\"],\"resources\":[\"nightly-report\"]}]}"));

   CLICopy

   kode request POST /v1/tokens --body '{"name": "vendor-report", "owner": "acme", "expires_in_days": 30, "max_live_runs": 2, "grants": [{"kind": "pipeline-runs", "verbs": ["read", "logs", "run"], "resources": ["nightly-report"]}]}'

2. Give the token value to the vendor through your secret store.

3. Give the vendor the rule to send a key with each start, such as the date. A retry with the same key answers the first run.

Close-out

1. Show the tokens. Make sure that the grants of the new token name only pipeline-runs.

Create a token that runs capsules from one set of images

Reason for the task

Give a CI job the right to run capsules from node: images, for at most 600 seconds, and to see only its own capsules.

Job set-up

• Access: you. The owner is your handle or a team where you are an active member.
• References: POST /v1/tokens.

Procedure

1. Create the token with one grant on capsules that has own and limits. Set ten runs in flight.

   PythonCopy

   t = kl.request("POST", "/v1/tokens", body={    "name": "ci-node",    "owner": "acme",    "max_live_runs": 10,    "grants": [        {            "kind": "capsules",            "verbs": ["read", "logs", "run", "lifecycle"],            "resources": ["*"],            "own": True,            "limits": {                "images": ["node:*"],                "max_timeout_s": 600,                "network": True            }        }    ]})

   TypeScriptCopy

   const t = (await kl.request("POST", "/v1/tokens", {  name: "ci-node",  owner: "acme",  max_live_runs: 10,  grants: [    {      kind: "capsules",      verbs: ["read", "logs", "run", "lifecycle"],      resources: ["*"],      own: true,      limits: {        images: ["node:*"],        max_timeout_s: 600,        network: true      }    }  ]})) as { _id: string; token: string };

   GoCopy

   var t map[string]anyerr := kl.Request("POST", "/v1/tokens", kloudlite.RequestOptions{    Body: map[string]any{        "name": "ci-node",        "owner": "acme",        "max_live_runs": 10,        "grants": []map[string]any{            {                "kind": "capsules",                "verbs": []string{"read", "logs", "run", "lifecycle"},                "resources": []string{"*"},                "own": true,                "limits": map[string]any{                    "images": []string{"node:*"},                    "max_timeout_s": 600,                    "network": true,                },            },        },    },    Out:  &t,})if err != nil {    log.Fatal(err)}

   RubyCopy

   t = kl.request("POST", "/v1/tokens", body: {  name: "ci-node",  owner: "acme",  max_live_runs: 10,  grants: [    {      kind: "capsules",      verbs: ["read", "logs", "run", "lifecycle"],      resources: ["*"],      own: true,      limits: {        images: ["node:*"],        max_timeout_s: 600,        network: true      }    }  ]})

   JavaCopy

   String t = kl.request(new Kloudlite.RawRequest().method("POST").path("/v1/tokens")    .body("{\"name\":\"ci-node\",\"owner\":\"acme\",\"max_live_runs\":10,\"grants\":[{\"kind\":\"capsules\",\"verbs\":[\"read\",\"logs\",\"run\",\"lifecycle\"],\"resources\":[\"*\"],\"own\":true,\"limits\":{\"images\":[\"node:*\"],\"max_timeout_s\":600,\"network\":true}}]}"));

   CLICopy

   kode request POST /v1/tokens --body '{"name": "ci-node", "owner": "acme", "max_live_runs": 10, "grants": [{"kind": "capsules", "verbs": ["read", "logs", "run", "lifecycle"], "resources": ["*"], "own": true, "limits": {"images": ["node:*"], "max_timeout_s": 600, "network": true}}]}'

2. Put the token value in the secret store of the CI system.

Close-out

1. Show the tokens. Make sure that the grant shows own and the limits.

Use a token with the CLI and the SDKs

Reason for the task

Run a script, a CI job, or an SDK client with a token and no browser login.

Job set-up

• Access: the secret of the token.
• References: SDKs.

Procedure

1. Set the API origin and the token in the environment of the program. The SDKs and kode read both.

   CLICopy

   export KODE_URL=https://dev.kloudlite.ioexport KODE_TOKEN=klt_...

2. Run the program. For a direct call, send the token as a bearer.

   CLICopy

   curl -H "Authorization: Bearer $KODE_TOKEN" https://dev.kloudlite.io/v1/workspaces

Close-out

1. Make sure that the call answers 200. A 401 means that the token is wrong, expired, revoked, or outside its grants for that route.

List your tokens

Reason for the task

Find the tokens that you made, their reach, their expiry, and their last use.

Job set-up

• Access: you, signed in with the console or a CLI login.
• References: GET /v1/tokens.

Procedure

1. Show the tokens. Add ?owner= to see the tokens of one reach.

   PythonCopy

   for t in kl.request("GET", "/v1/tokens"):    print(t["_id"], t["name"], t["reach"], t["expiresAt"], t["lastUsedAt"])

   TypeScriptCopy

   const tokens = (await kl.request("GET", "/v1/tokens")) as { _id: string; name: string; expiresAt: string; lastUsedAt: string | null }[];for (const t of tokens) console.log(t._id, t.name, t.expiresAt, t.lastUsedAt);

   GoCopy

   var tokens []map[string]anyerr := kl.Request("GET", "/v1/tokens", kloudlite.RequestOptions{Out: &tokens})if err != nil {    log.Fatal(err)}for _, t := range tokens {    fmt.Println(t["_id"], t["name"], t["expiresAt"], t["lastUsedAt"])}

   RubyCopy

   kl.request("GET", "/v1/tokens").each { |t| puts [t["_id"], t["name"], t["expiresAt"], t["lastUsedAt"]].join(" ") }

   JavaCopy

   System.out.println(kl.request(new Kloudlite.RawRequest().method("GET").path("/v1/tokens")));

   CLICopy

   kode request GET /v1/tokens

Close-out

1. Make sure that each token in the list is still in use. A lastUsedAt of null means that no use is recorded.

Revoke a token

Reason for the task

Stop a token that is unused or exposed.

Job set-up

• Access: you. Only the creator can revoke a token.
• References: DELETE /v1/tokens/{id}.

Procedure

1. Find the _id of the token as in task 10-20-00-005.

2. Delete the token. Replace {id} with the _id of the token.

   PythonCopy

   kl.request("DELETE", "/v1/tokens/{id}")

   TypeScriptCopy

   await kl.request("DELETE", "/v1/tokens/{id}");

   GoCopy

   if err := kl.Request("DELETE", "/v1/tokens/{id}", kloudlite.RequestOptions{}); err != nil {    log.Fatal(err)}

   RubyCopy

   kl.request("DELETE", "/v1/tokens/{id}")

   JavaCopy

   kl.request("DELETE", "/v1/tokens/{id}");

   CLICopy

   kode request DELETE /v1/tokens/{id}

Close-out

1. Show the tokens. Make sure that the _id is gone.

Troubleshooting