---
title: 'flexkit tokens'
description: 'List, create and revoke project API tokens from the terminal, and use them in CI with FLEXKIT_TOKEN.'
---

# `flexkit tokens`

Manages the project's [API tokens](/docs/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

```bash
flexkit tokens <subcommand> [arguments] [options]
```

Running `flexkit tokens` without a subcommand runs `flexkit tokens ls`. Tokens need a signed-in person: run [`flexkit login`](/docs/cli/login) first. See [Permissions](#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`.

```bash
flexkit tokens ls [--json]
```

### Examples

```bash
# 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`.

```bash
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](/docs/dashboard/members) 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

```bash
# 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`.

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

### Examples

```bash
# Revoke a token by name
flexkit tokens rm "Storefront"

# Revoke by id without a prompt
flexkit tokens rm 42 --yes
```

## Options

| Option                  | Subcommands | Description                                                                       |
| ----------------------- | ----------- | --------------------------------------------------------------------------------- |
| `--role <role>`, `-r`   | `create`    | `viewer` (default), `editor`, `contributor` or `developer`.                       |
| `--space <space>`, `-s` | `create`    | Space code or id the token may read. Repeatable; commas separate several.         |
| `--yes`, `-y`           | `rm`        | Skip the confirmation prompt.                                                     |
| `--json`                | all         | Print JSON on stdout. For `create`, the JSON includes the token in `token.value`. |
| `--project <ID>`, `-p`  | all         | Project to use. Default: the [linked](/docs/cli/link) project.                    |

See also the [global options](/docs/cli/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`:

```yaml filename=".github/workflows/flexkit.yml"
- name: Deploy the schema
  run: npx flexkit deploy
  env:
    FLEXKIT_TOKEN: ${{ secrets.FLEXKIT_TOKEN }}
    FLEXKIT_PROJECT_ID: abcdefghij
```

```bash
# 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.


---

[View full sitemap](/docs/sitemap.md)