flexkit tokens

Manages the project’s API tokens: credentials that let apps, scripts and CI pipelines call the project without a person signed in. Each token has its own role and, optionally, spaces whose data it may read. These are the same tokens as in the dashboard (project API → Access Tokens).

Synopsis

flexkit tokens <subcommand> [arguments] [options]

Running flexkit tokens without a subcommand runs flexkit tokens ls. Tokens need a signed-in person: run flexkit login first. See Permissions.

tokens ls

List the project’s tokens, newest first: id, name, role, spaces, the last six characters of the token, who created it and when. The full token is only shown once, when it is created. Tokens that automations manage for themselves are not listed. Alias: list.

flexkit tokens ls [--json]

Examples

# List tokens
flexkit tokens ls
 
# Names and roles only
flexkit tokens ls --json | jq -r '.tokens[] | "\(.name) \(.role)"'
 
# Tokens of another project
flexkit tokens ls --project abcdefghij

tokens create

Create a token and print it once. Copy it into your secret store right away: it can’t be shown again, and a lost token has to be replaced. Alias: add.

flexkit tokens create <name> [--role <role>] [--space <space>]... [--json]

• --role is viewer (default), editor, contributor or developer. Owner tokens can’t be created. Choose the smallest role the integration needs; see members and permissions for what each role may do.
• --space adds a space whose data the token may read, by space code or id. Repeat it or separate codes with commas. Without --space, the token reads only data that isn’t restricted to a space.
• Tokens don’t expire. Revoke them with flexkit tokens rm when they are no longer needed.

The token is printed alone on stdout and the notes go to stderr, so $(flexkit tokens create …) or a pipe receives only the token. With --json, the response, including the token in token.value, is printed on stdout for scripts.

Examples

# A read-only token for a storefront
flexkit tokens create "Storefront"
 
# A developer token for CI
flexkit tokens create "GitHub Actions" --role developer
 
# An editor token that also reads the sales and marketing spaces
flexkit tokens create "Sales sync" --role editor --space sales --space marketing
 
# Create a token and store it as a GitHub Actions secret, without showing it
flexkit tokens create "GitHub Actions" --role developer | gh secret set FLEXKIT_TOKEN
 
# Read the token from JSON
flexkit tokens create nightly-export --json | jq -r '.token.value'

tokens rm

Revoke a token by its id or exact name (case-insensitive). Apps and scripts that use it stop working at once. The command asks for confirmation; pass --yes in scripts. Aliases: remove, revoke.

flexkit tokens rm <idOrName> [--yes] [--json]

Examples

# Revoke a token by name
flexkit tokens rm "Storefront"
 
# Revoke by id without a prompt
flexkit tokens rm 42 --yes

Options

See also the global options.

Use a token in CI

Set the token as the FLEXKIT_TOKEN environment variable and the project as FLEXKIT_PROJECT_ID (or pass --project). Every flexkit command then runs as the token, with the token’s role and spaces, without flexkit login:

- name: Deploy the schema
  run: npx flexkit deploy
  env:
    FLEXKIT_TOKEN: ${{ secrets.FLEXKIT_TOKEN }}
    FLEXKIT_PROJECT_ID: abcdefghij

# Or for one command in a shell
FLEXKIT_TOKEN=flk-... FLEXKIT_PROJECT_ID=abcdefghij flexkit records ls products --json

--token takes precedence over FLEXKIT_TOKEN. Changes a token makes are attributed to the member who created it.

Permissions

• Needs a signed-in Owner or Developer (flexkit login). API tokens can’t manage tokens: with FLEXKIT_TOKEN or --token, every flexkit tokens command fails with “A user session is required”, so a leaked token can’t create more tokens or revoke others.
• You can’t give a token more than you have: a token’s role can be at most yours (owner tokens can’t be created at all), and a Developer can only give a token spaces they belong to. Owners belong to every space.
• Any Owner or Developer can revoke any token of the project, including tokens other members created.