API tokens

Description and operation

General

An API token gives git over HTTPS and the container registry access to one owner. The owner is your handle, or a team where you are an active member. It does not open the /v1 API; the API and the SDKs use your CLI login.

A token has a name of 1 to 60 characters. The platform shows the value once and stores only a digest, so a lost token must be revoked and replaced. Every active member of a team can see and revoke the team's tokens.

Tasks

Create an API token

Reason for the task: Give a program git and registry access to one owner.

Job set-up

• Access: you. A team token needs an active team member.
• References: POST /v1/tokens.

Procedure

1. Create the token. Set owner and name.

   PythonCopy

   from kloudlite import Kloudlitekl = Kloudlite()t = kl.request("POST", "/v1/tokens", body={"owner": "acme", "name": "ci"})print(t["_id"])  # t["token"] is the value

   TypeScriptCopy

   import { Kloudlite } from "./index.ts";const kl = new Kloudlite();const t = (await kl.request("POST", "/v1/tokens", { owner: "acme", name: "ci" })) as { _id: string; token: string };console.log(t._id); // t.token is the value

   GoCopy

   kl := kloudlite.New(kloudlite.Options{})var t map[string]anyerr := kl.Request("POST", "/v1/tokens", kloudlite.RequestOptions{    Body: map[string]any{"owner": "acme", "name": "ci"},    Out:  &t,})if err != nil {    log.Fatal(err)}fmt.Println(t["_id"]) // t["token"] is the value

   RubyCopy

   require_relative "kloudlite"kl = Kloudlite::Client.newt = kl.request("POST", "/v1/tokens", body: { owner: "acme", name: "ci" })puts t["_id"] # t["token"] is the value

   JavaCopy

   var kl = new Kloudlite();// The JSON answer has "_id" and "token".String t = kl.request(new Kloudlite.RawRequest().method("POST").path("/v1/tokens")    .body("{\"owner\":\"acme\",\"name\":\"ci\"}"));

   CLICopy

   kloudlite request POST /v1/tokens --body '{"owner": "acme", "name": "ci"}'

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 003. Make sure that the new token is listed.

Use a token with git and the registry

Reason for the task: Clone, push and pull images from a program.

Job set-up

• Access: you.
• References: POST /v1/tokens.

Procedure

1. Use the token as the password for git. The user name is ignored; use x.

   CLICopy

   git clone https://x:API_TOKEN@CLONE_HOST/OWNER/NAME.git

2. Sign in to the registry with the owner as the user name and the token as the password.

   CLICopy

   docker login REGISTRY_HOST -u OWNER

Close-out

1. Make sure that the clone and docker login finish without an error.

Show your tokens

Reason for the task: List the active tokens of one owner.

Job set-up

• Access: you. A team's tokens need an active team member.
• References: GET /v1/tokens.

Procedure

1. Show the tokens. Set owner to your handle or a team handle.

   PythonCopy

   for t in kl.request("GET", "/v1/tokens", query={"owner": "acme"}):    print(t["_id"], t["name"])

   TypeScriptCopy

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

   GoCopy

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

   RubyCopy

   kl.request("GET", "/v1/tokens", query: { owner: "acme" }).each { |t| puts "#{t["_id"]} #{t["name"]}" }

   JavaCopy

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

   CLICopy

   kloudlite request GET /v1/tokens --query owner=acme

Close-out

1. Make sure that each token in the list is still in use.

Revoke a token

Reason for the task: Stop a token that is unused or exposed.

Job set-up

• Access: you. A team's tokens need an active team member.
• References: DELETE /v1/tokens/{id}.

Procedure

1. Find the _id of the token as in task 003.

2. Delete the token. Replace ID with its _id.

   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

   kloudlite request DELETE /v1/tokens/ID

Close-out

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

Troubleshooting