API Tokens

An API token is a long-lived bearer credential for the Conduit REST API. Use a token in a CI/CD pipeline, a cron job, a server-to-server integration, or a script. These are the places where a short-lived JWT is not practical to refresh.

This page covers how to manage tokens in the web UI. The API reference has the HTTP shape and a comparison of the two authentication methods. See Using the API → Authentication and API Tokens (API reference).

Creating a token

  1. Open the user menu and go to API tokens (/app/settings/api-tokens).
  2. Click + New Token.
  3. Complete the form:
Field Notes
Token name A label that only you see, for example "GitHub Actions, staging".
Expiry Select a duration, or Never. A token for one specific use must always have an expiry.
Allowed IPs An optional allowlist. Enter one IP address or CIDR block per line. Both IPv4 and IPv6 work. Leave it blank to allow any source IP address.
  1. Click Create token.

Conduit shows the raw token value one time, at the top of the list page. Copy it immediately. Conduit never shows it again.

conduit_aB3c...raw-token-shown-once...

If you lose the token, revoke it and create a new one.

Using a token

Send the token in the Authorization header on every API request:

Authorization: Bearer conduit_aB3c...

The same header format works for an API token and for a session JWT. Conduit tries JWT validation first, and then falls back to API tokens.

Limiting the damage from a leak

Two restrictions limit the damage when a token leaks:

  • Expiry. Set the shortest practical lifetime. To rotate a token, issue a new one before the old one expires.
  • Allowed IPs. If your CI runner or your server has stable public IP addresses, list them. Conduit rejects a request from any other source with a 401. CIDR notation works (10.0.0.0/8, 2001:db8::/32).

Listing and revoking

The list page shows every active token. Each row has the creation date, the expiry (or Never expires), and the time of the most recent successful API request (or Never used).

Click Revoke next to a token to invalidate it immediately. Conduit rejects the next call from a revoked token.

CAUTION: Revocation is permanent. You cannot reactivate a revoked token. Create a new one instead.

The Last used column shows which tokens no longer have an active caller. A token with no use for several months is a good candidate for revocation.

Issue one token for each integration. A revoked CI secret then does not stop an unrelated production script. Rotate your tokens regularly, even when no token leaked. This is most important for a token with no expiry.

Next steps