API keys
Weik.io 2026.2The weikio CLI or a pipeline signs in with an API key. A key has the grants you give it or all your access, and never more rights than its owner. Video
Watch: Projects and environments, 3:07
The video explains projects and environments, and how people and pipelines get their roles through grants and API keys.
This part of the video couldn't be loaded.
On this page
The weikio CLI and your pipelines sign in with API keys, which you see once, when they’re created. Each key belongs to a user and has an expiry.
A key’s access is Only these or All my access, and never more than your own. An Only these key can use only those of your projects and roles that you pick when you create it, but not a role that you get only from a claim mapping. An All my access key can do everything you can. If you get a new project or role later, the key gets it too.
When you remove a role from someone, their keys lose it too. If you create an All my access key while signed in through an identity provider, the key also has the roles that the provider’s claim mappings give you, by default for 30 days after your last sign-in there.
Create a key#
You can create keys for yourself within your own grants:
$ weikio apikey create --name laptop-anna --expires 90d --grant finance/deployer@devtestTarget: 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_****************************| Flag | What it does |
|---|---|
-- |
Gives the key a grant, written project/. Repeat it for each grant. |
--, --apis |
Limits a key with one grant to the integrations or APIs you list. |
-- |
Makes an All my access key. It can’t be used with --, or with -- and the flags that limit a grant. |
-- |
Sets how long the key lasts, such as 365d, or the date it stops working. A key without it lasts 90 days, or 30 days with --. -- makes a key that never expires. |
Give every key an expiry.
To create a key that follows your access as it changes, give --all-access:
$ weikio apikey create --name laptop-docs --all-accessTarget: https://hub.example, user admin@local (caller)
api-key laptop-docs created (id 01m7qrbn0rtjt36b07e8d01eh4, expires 2027-02-16, grants all the owner's access)
API key (shown once): wk_...In the admin UI, you pick Only these or All my access in the Access field when you create a key under Settings › Access › API keys. For a key you create for another person, the choice is All their access.
On a machine with a browser, weikio login https://acme.example creates an All my access key for that machine through the approval page of your Weik.io installation. The key expires in 90 days, or in 30 days when you’re a platform administrator. Before you approve the key, check its details on the page:
- The machine’s name
- The address the request came from
- The key’s expiry
- The access you have now, under the line
All your access, now and as it changes.
A grant from a claim mapping shows its provider, as in from entra. The key never appears in the browser’s address.
A key for a pipeline#
Give each pipeline a separate user with the deployer role and one key per environment. A devtest key then has no rights in 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@devtestTarget: 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_****************************If you ask for more than the key’s owner was given, creating the key fails. To grant the rest, have a project administrator run the command at the end of the error:
$ weikio apikey create --name finance-ci-prod --user ci@example.com --grant finance/deployer@devtest,productionTarget: 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,productionStore 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 jsonKeep integrations in Git shows the rest of the pipeline.
Platform administrator keys#
An Only these key acts as a platform administrator only if you create it with --platform-admin, and only while its owner is one. An All my access key acts as one whenever its owner is one. A key you create with --grant alone can use only its grants, even when you’re a platform administrator. With such a key, weikio whoami prints Platform admin: no.
To use --platform-admin, or --user to create a key for someone else, you must be a platform administrator on your own account, not through a claim mapping.
At the first start, the installation prints its first key, a platform administrator’s key, which you use to create named keys for the people and pipelines that need them. Save it as the install guide says.
A pipeline’s key can create 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.comNAME ID OWNER EXPIRES LAST USED GRANTS
finance-ci-devtest 01k7xq4b2c5f8g1j3k6m9n0p4s ci@example.com 2027-09-16 never finance/deployer@devtestThe list never shows the secret part of a key. For an All my access key, GRANTS shows all the owner's access.
| Command | What it does |
|---|---|
weikio describe apikey <keyId> |
Shows one key and all its grants |
weikio apikey revoke <keyId> |
Deletes the key, so the next request that uses it fails |
weikio problems lists your keys that expired, and for a platform administrator every key that expired.
In the admin UI the keys are under Settings › Access › API keys.
Rotate a key#
-
Create a new key with the same grants and a new expiry:
Terminal$ weikio apikey create --name finance-ci-devtest-2027 --user ci@example.com --expires 365d --grant finance/deployer@devtest -
Put the new key in the pipeline’s secret.
-
Revoke the old key once the pipeline runs with the new one:
Terminal$ weikio apikey revoke <old keyId>
To see whether anything still makes changes with the old key, run weikio audit query --actor <old keyId>.