Skip to content
Weik.ioDocs
2026.2
Try Weik.io

API keys

Weik.io 2026.2

The 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.

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:

Terminal
$ weikio apikey create --name laptop-anna --expires 90d --grant finance/deployer@devtest
You see
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_****************************
Flag What it does
--grant Gives the key a grant, written project/role@environments. Repeat it for each grant.
--integrations, --apis Limits a key with one grant to the integrations or APIs you list.
--all-access Makes an All my access key. It can’t be used with --platform-admin, or with --grant and the flags that limit a grant.
--expires 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 --platform-admin. --expires never 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:

Terminal
$ weikio apikey create --name laptop-docs --all-access
You see
Target: 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:

Terminal
$ 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
You see
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_****************************

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:

Terminal
$ weikio apikey create --name finance-ci-prod --user ci@example.com --grant finance/deployer@devtest,production
You see
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:

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

Keep 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#

Terminal
$ weikio get apikeys --user ci@example.com
You see
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 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#

  1. 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
  2. Put the new key in the pipeline’s secret.

  3. 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>.

Sign in to the live demo

Sign in with the shared viewer account. It can open every screen of the example projects but can't change anything.

E-mail
viewer@demo.weik.io
Password
try-weikio-live-demo
Open the live demo