Pick a method
OpenKey
Browser or paste sign-in. Best for interactive use.
OpenKey device
The owner approves on their phone. Best for agents and servers.
Local key
Private-key sign-in. Best for CI against a key you control.
publisher for Share publishing or
agent-secrets for an agent that reads API keys. Signing an existing profile
in again for a different purpose can replace the session another app relies
on.
Start with a profile
tc init creates a profile directory, generates a keypair, and can optionally sign in immediately.
Sign in
Request only what you need
--manifest asks OpenKey for one app manifest’s permissions instead of the
default abilities. The owner sees every capability on the consent page and may
uncheck some; the JSON result lists permissions (approved) and declined.
A profile that already recorded an owner is held to that owner on every later
login. A live session is only replaced by a scope that keeps everything it
holds and lasts at least as long; anything else fails with
SESSION_IN_USE
and saves nothing. If another tc or MCP process holds the profile while a
login commits, the CLI waits up to 45 seconds and then fails with
PROFILE_LOCK_TIMEOUT; retry once the other process finishes.
Device login for agents and servers
Use device login when the owner cannot open a browser on the machine runningtc. It requires a KV-scoped manifest.
capabilities/read in one space. It
cannot grant SQL, secrets, or encryption; use browser or paste login with a
manifest for those.
Which OpenKey key signed in
An OpenKey account can hold several keys, and each key is a separate owner with its own spaces. OpenKey preselects the account’s primary key on CLI and agent approval pages, and other keys sit behind Use a different key. To change it, open a key from Your Keys on the OpenKey dashboard with Manage, then choose Make primary. Only OpenKey-managed keys can be primary.CLI 1.1.0 beta records whether the approving key was primary (
tc auth status
shows Primary Key) and warns on stderr when it was not. tc auth login --owner <did> no longer needs --manifest. --paste also accepts the eight-character
code OpenKey shows instead of the full delegation.Check state
tc auth status shows which DID is active and whether the profile has a stored session; it does not check that the session is still valid. tc context reports the selected profile, owner and session DIDs, host, space, and local session state (present, expired, missing, or unknown-expiry) as JSON, without contacting the node.
When a session expires
OpenKey browser and paste sessions last 7 days unless you pass--expiry;
device sessions default to 30 days, their maximum. When tc context shows
the session as expired, sign in again with the same command you used to
create it.
In CLI 1.1.0 beta, every command run on an expired session fails with
AUTH_REQUIRED (exit 3) before contacting the node, and the hint names the right sign-in for the profile: scoped
paste login for a delegate, --method local for a local key, and --method openkey for an OpenKey owner. tc auth login and tc auth logout on a
profile that does not exist fail with PROFILE_NOT_FOUND.OpenKey host overrides
OpenKey auth uses this resolution order:TC_OPENKEY_HOSTprofile.jsonopenkeyHosthttps://openkey.so
Automation
tc auth login --method local signs in with the profile’s own stored key, or
generates one, without a browser. TC_PRIVATE_KEY and --private-key are
read by tc vault, tc vars, and tc secrets, not by auth login.
In a non-interactive run, an OpenKey tc auth login without --paste,
--no-popup, or --device fails with INTERACTIVE_LOGIN_REQUIRED (exit 2)
instead of waiting for a browser.
tc auth rotate replaces the profile’s session key and signs in again; it
accepts --paste and --no-popup.