API keys

The weikio CLI and your pipelines sign in with API keys. A key belongs to a user, carries grants of its own and an expiry, and is shown once when it’s created. A key never has more rights than its owner was granted directly, at the time of each request, so removing a role from a person removes it from their keys too.

Create a key#

Anyone signed in may create keys for themselves within their own grants:

$ weikio apikey create --name laptop-anna --expires 90d --grant finance/deployer@devtest

Target: https://hub.example, user anna@example.com (caller)
api-key laptop-anna created (id 01k7xq3m8d9h2vqz4n6p5r7t2w, expires 2026-12-15, grants finance/deployer@devtest)
API key (shown once): wk_01k7xq3m8d9h2vqz4n6p5r7t2w_****************************

--grant accepts project/role@environments and is repeated for several grants. --integrations and --apis narrow a single grant to the integrations or APIs it covers. A key without --expires doesn’t expire, so give every key an expiry.

On a machine with a browser, weikio login https://acme.example creates a key for that machine through the hub’s approval page, which shows the machine’s name, the address the request came from, the key’s rights and its expiry before you approve it. The key never appears in the browser’s address.

A key for a pipeline#

Give each pipeline its own user and one key per environment, with the deployer role. A devtest key then can’t touch production, even if someone edits the workflow:

$ weikio user create ci@example.com --display-name "Finance CI"
$ weikio member add finance ci@example.com --role deployer --env devtest
$ weikio apikey create --name finance-ci-devtest --user ci@example.com --expires 365d --grant finance/deployer@devtest

Target: https://hub.example, user ci@example.com (--user)
api-key finance-ci-devtest created (id 01k7xq4b2c5f8g1j3k6m9n0p4s, expires 2027-09-16, grants finance/deployer@devtest)
API key (shown once): wk_01k7xq4b2c5f8g1j3k6m9n0p4s_****************************

A key that asks for more than its owner was given is refused, with the command that would grant it:

$ weikio apikey create --name finance-ci-prod --user ci@example.com --grant finance/deployer@devtest,production

Target: https://hub.example, user ci@example.com (--user)
error: The grant goes beyond what 'ci@example.com' was given directly: 'ci@example.com' has the role 'deployer' in project 'finance' only in environment 'devtest'. Ask for less, or have a project administrator grant it with:
         weikio member add finance ci@example.com --role deployer --env devtest,production

Store the key as a secret of the pipeline. The CLI uses a key from WEIKIO_API_KEY or from standard input, so a workflow step runs the CLI with no login:

$ WEIKIO_API_KEY="$CI_KEY" weikio get environments --server https://hub.example -o json

Keep integrations in Git shows the whole pipeline.

Platform administrator keys#

A key acts as a platform administrator only when it was created with --platform-admin and its owner still is one. A key created with --grant alone acts in its grants, even when the person who created it administers the platform, and weikio whoami with it prints Platform admin: no. --platform-admin, and --user for someone else, need a caller who is a platform administrator by their own setting, not through a claim mapping.

The first key the installation prints at the first start is a platform administrator’s key. Save it as the install guide says, and use it to create named keys for the people and pipelines that need them.

A key run by a pipeline creates keys only within its own grants, so a devtest key can’t create a production key even when its owner has both.

List, check and revoke#

$ weikio get apikeys --user ci@example.com

NAME                 ID                           OWNER             EXPIRES      LAST USED   GRANTS
finance-ci-devtest   01k7xq4b2c5f8g1j3k6m9n0p4s   ci@example.com    2027-09-16   never       finance/deployer@devtest

The list never shows the secret part. weikio describe apikey <keyId> shows one key with its full grant list. weikio apikey revoke <keyId> deletes it, so the next request that uses it is refused. weikio problems lists the keys that expired, your own, or every key for a platform administrator. In the admin UI the keys are under Settings › Access › API keys.

Rotate a key#

To rotate a pipeline’s key, create a new key with the same grants and a new expiry, put it in the pipeline’s secret, and revoke the old key once the pipeline runs with the new one:

$ weikio apikey create --name finance-ci-devtest-2027 --user ci@example.com --expires 365d --grant finance/deployer@devtest
$ weikio apikey revoke <old keyId>

The audit trail records every change with the key that made it, so weikio audit query --actor <old keyId> shows whether anything still made changes with the old key.