# Service tokens

A seekrit **service token** (`skt_…`) is a machine credential for CI jobs, Docker builds,
Kubernetes workloads, and agent sandboxes: each one is an independent principal **bound to one
application environment**, decrypting with no passphrase and no browser. That binding selects the
org, app, and environment it resolves at runtime, plus the group slices composed into it, and a
token can be revoked on its own without touching any other.

## How they work

Keep one `SEEKRIT_TOKEN`. Its v2 format bundles an independent authentication secret and
private key: `skt_<id>_v2.<auth-secret>.<private-key>`. The runner, CLI, SDKs, and Terraform
provider split it internally. **Only `skt_<id>_v2.<auth-secret>` goes into HTTP requests.**
The private key stays local to unwrap the environment key and decrypt the returned ciphertext.

The server stores the **SHA-256 hash of the authentication component** and the **public key**.
An intercepted authentication component can fetch encrypted payloads and use its API permissions,
but it cannot decrypt the environment secrets. Theft of the complete local bundle still exposes
both capabilities. HTTPS remains required to protect the authentication credential.

Legacy tokens have no independent auth secret. Updated tools refuse to send them. Upgrade your
tools, mint a replacement token with the same binding and grants, replace `SEEKRIT_TOKEN`, and
revoke the old token. Legacy keys still work with offline archive decryption. Revocation cannot
undo access to previously copied keys or plaintext.

Because tokens are generated on the client, the full token is shown **once** at creation. Copy it
then; it cannot be retrieved later.

## Creating a token

**In the web dashboard:** Organization → **Service tokens** → **Mint token**. You can also mint from
where you notice the need for one — an environment's **Access** panel, the **no token** warning
on a matrix column, the application setup checklist, or the **Connect** panel — and those pre-fill the
binding. Either way, copy the `skt_…` value from the one-time dialog.

Minting in an organization that has no application environment yet doesn't dead-end: the dialog offers
to create an application (its environments come with it) and then carries on with the binding
pre-selected.

![The Service tokens page listing three tokens with the environment each is bound to, its id, status, and last use](https://seekrit.dev/screenshots/original/dashboard-service-tokens.webp)

*The Service tokens page. Each token names the one app environment it is bound to, and a revoked token stays listed — the id remains attributable in the audit trail.*

**With the CLI**, bind the token to an application environment. Creation auto-grants that
environment's key **and** every group composed into it (at the matching slug):

```bash
seekrit token create --name ci-deploy --app storefront --env production
# prints:  skt_XXXXXXXX_...    (save it now)
```

To also authorize an alternate group slice for `run --with` overrides, add `--allow`:

```bash
seekrit token create --name dev --app storefront --env dev --allow auth-providers=staging
```

Pass `--no-grant` to mint the token without any grants, then grant environments explicitly:

```bash
seekrit token create --name ci-deploy --app storefront --env production --no-grant
seekrit grant --token skt_XXXXXXXX --app storefront --env production
```

## Admin tokens

By default a token holds **member**-level API access — its real power is the environment keys
wrapped to it. Pass `--admin` to mint an **org-scoped admin token** that also passes admin-gated
routes: creating apps, groups, and environments, composing groups, granting keys, and minting
further tokens. This is what lets automation and AI agents provision structure headlessly, with no
browser session.

```bash
seekrit token create --name agent-admin --admin
# org-scoped: no --app/--env needed
```

An admin token needs no environment binding to provision, but you can still bind one
(`--admin --app storefront --env production`) so it can both manage structure and decrypt that
environment. Only an admin caller (an admin user, or another admin token) may create an admin
token — capability never escalates itself. Scope admin tokens tightly and prefer a short lifetime.

## Using a token

Set it as `SEEKRIT_TOKEN`; it selects the org, app, and environment on its own:

```bash
export SEEKRIT_TOKEN=skt_XXXXXXXX_...

seekrit export --format dotenv
seekrit run -- ./deploy.sh
```

Service tokens never need a passphrase — their private key is in the token string. A token can
only read or write the environments it was granted (its bound env + composed groups); it cannot
reach other environments in the org.

## Granting and revoking

Grants are per-environment. Grant a token from any environment's **Access** panel, or with
`seekrit grant --token <id> --app <app> --env <env>`. When a token is retired:

```bash
seekrit token revoke skt_XXXXXXXX
```

Revocation takes effect on the token's next request: revoking drops the cached copy of the token
record that authentication reads, everywhere at once, as part of the same operation. In the rare
case that a copy outlives the revoke, it is re-checked against the database within a minute of
continued use, so a stale copy corrects itself rather than lingering.

If you need a hard cutoff — a leaked token, a departing teammate — revoke and then **rotate the
environment key**. Revoking the grant doesn't rotate the key, and rotation is what makes a DEK the
token already fetched useless; see
[Access & key grants](/docs/concepts/access-control#revocation-vs-rotation).

## Deleting

Revocation is the reversible-safe step: a revoked token authenticates nothing and stops counting
against your plan's token limit, but it stays in the list so you keep the audit trail. When you want
it gone for good, delete it:

```bash
seekrit token delete skt_XXXXXXXX
```

Deletion is only allowed **after** a token is revoked, and it can't be undone — it drops every
environment/KMS key grant that was wrapped to the token and hides it from your token list. The token
record itself is retained for the audit trail (a soft delete); it just no longer appears anywhere or
holds any keys. In the dashboard the **delete** action appears in the token's row once it shows as
`revoked`.

> **Warning:** Treat a service token like a password with decryption power. Scope it to only the environments
>   it needs, store it in your platform's secret store (not in the repo), and rotate the environment
>   key if a token leaks.

## Listing tokens

```bash
seekrit token list
```

Shows each token's id, name, status (active / expired / revoked), and last-used time.

A token's **name** is the only part you can change afterwards — hover a row on the dashboard's
Service tokens page and click the pencil. Its role, environment binding, and expiry are fixed at
mint time: those are what the credential authorizes, and a credential whose authority could be
edited after the fact would make the audit trail unreadable. To change any of them, mint a new
token and revoke the old one.

Last-used is a coarse "when was this seen" signal, not a request log: it is recorded off the read
path and settles within a couple of minutes, so a token that just resolved may still show its
previous time. Use it to spot a credential nobody uses any more — for per-request history, read the
[audit trail](/docs/concepts/security#audit-trail).

## Watching for leaked tokens

A real token that escapes into an archived repo or a retired CI pipeline is the
thing you can't see. [Honey tokens](/docs/guides/honey-tokens) are the other half
of that problem: decoy credentials, identical in format to the tokens above, that
unlock nothing and email your admins the instant anyone tries one. Plant one
alongside wherever your real credentials have historically ended up, and you find
out that a place has been read — instead of finding out later.

## Common questions

### What is a seekrit service token?

A machine credential (skt_...) bound to one application environment, so CI jobs, Docker builds, Kubernetes workloads, and agent sandboxes can decrypt with no passphrase and no browser. It carries an independent authentication secret and private key, and can be revoked on its own without affecting other tokens.

### How do I create a seekrit service token scoped to one environment?

Run seekrit token create --name <name> --app <app> --env <env>. Creation auto-grants that environment's key plus every group composed into it, and the full skt_... value is shown once — copy it immediately, since it can't be retrieved later.

### What can a stolen seekrit service token do?

It depends which half leaked. The authentication component alone can fetch encrypted payloads and use the token's API permissions but cannot decrypt environment secrets, since the server only stores its hash and public key. The complete local bundle, private key included, can decrypt everything the token was granted — so revoke it and rotate the affected environment's key.

### How do I let a service token manage structure, not just decrypt secrets?

Mint it with --admin: seekrit token create --name agent-admin --admin. An admin token passes admin-gated routes — creating apps, groups, and environments, granting keys, minting further tokens — with no environment binding required, though you can still bind one so it can also decrypt. Only an admin caller can create an admin token.

### Does revoking a service token rotate the environment's encryption key?

No. Revoking the token stops it from authenticating on its next request, but the environment's data key is unchanged, so any plaintext or key material the token already fetched is not invalidated. For a hard cutoff after a leak, revoke the token and then rotate the environment key.
