ts api-key

Create or revoke a single API key. API-key login is the credential a script or CI job uses, so this is what a scripted setup reaches for when it needs to bootstrap its own access.

Usage

ts api-key <name>
ts api-key new <name> [--expires-in-days=N]
ts api-key delete <name> [--force]

Description

ts api-key new creates a key and prints it once. Nothing recovers it afterwards — the server keeps a hash, and ts api-keys shows only a last-four cue — so a key you lose has to be revoked and replaced rather than looked up. Capture it at creation or not at all.

ts api-key <name> shows one key's metadata: when it was created, when it expires, when it was last used. Useful for the question you actually have about a key, which is usually whether anything is still using it.

ts api-key delete revokes one. It prompts unless you pass --force; without a terminal, --force is required rather than assumed.

Keys are found by the name you gave them. The server has no by-name lookup, so the command resolves the name against the key list — and if two active keys share a name, it says so rather than guessing, because revoking the wrong one breaks something that is still in use. Pass the id in that case.

There is deliberately no renew action. The API offers create and delete and nothing between them, and re-minting under the same name is not a renewal: a key's name is its login identity, so what comes back is a different credential wearing a familiar name. Revoke and create explicitly instead.

There is also no system variant. The server can attach a key to the SYSTEM account, but no HTTP contract reaches that — only the Administration site's own dialog does.

Options

Flag	Description	Default/Values	Notes
--expires-in-days	Days until the new key expires.	Omit for a key that never expires	new only.
--force, -f	Revoke without confirming.		Required when there is no terminal.

Examples

# Mint a key for CI and capture it — this is the only time it is shown
ts api-key new ci-bot --expires-in-days=90

# What is this key, and is anything still using it?
ts api-key ci-bot

# Revoke it
ts api-key delete ci-bot --force

# Bootstrap a scripted setup: mint a key, then sign in with it
KEY=$(ts api-key new deploy-bot --format=json | jq -r '.[0].result.apiKey.key')
ts login --api-key="$KEY"

Exit Codes

0 on success. -1 when two active keys share the name, or when you answer no at the prompt. -4 when no account is signed in. -5 when the account is not a Server Administrator. -6 when no active key has that name.

Related Commands

• ts api-keys — Every key at once, with expiry and last use.
• ts login — Signing in with the key this creates.
• ts audit — When keys were created and revoked, and by whom.