Glob
Log in
Menu
Skip to the guide

Account and sync

API keys, identity keys, and recovery

Create scoped Data API keys, rotate or revoke them, and manage sync identity generations and recovery keys.

Use glob keys to manage access for external tools and to maintain your account's sync keys. These are different kinds of key:

Kind Purpose
Data API key Gives an external tool permission to read or change records within its scope.
Sync identity Your account's numbered identity generation for document keys.
Recovery key A second way to open the account's sync encryption if you lose the sync passphrase.

Data API key commands are available on macOS and Linux. keys identity, keys recovery, and keys rotate without an ID are available in the Linux CLI. Network access is required. See installation for the Linux build's HTTPS requirements.

All commands on this page accept --json. They require your configured server and signed-in account session. Giving an external tool a Data API key does not sign that tool into your account.

Create a Data API key

Start with read-only access and select the smallest reach you need:

glob keys create "Research helper" --agent-nickname Research --reach account
glob keys create "Writing helper" --agent-nickname Writer --reach account --write
glob keys create "Project helper" --agent-nickname Project --reach container --container-id <container-uuid>

glob keys create [name] accepts these options:

Option Meaning
[name] The key's label. Omit it for a Key label prompt.
--agent-nickname <name> The external tool's public identity. The CLI appends -AI unless the name already ends with it.
--agent-username <name> Supply the identity explicitly. Takes priority over --agent-nickname; the same suffix normalisation applies.
--reach account Scope access to your account's private records. Shared-container records are excluded by the relay.
--reach container Scope access to a container and records placed within it, including nested placements.
--container-id <uuid> Container UUID for container reach. Omit it for a Container UUID prompt.
--write Add record creation and updates to reading.
--preset readonly Read-only record access; the default.
--preset readwrite Record creation, reading, and updates.
--scope-json '<object>' Supply the complete canonical version 2 scope. Overrides the preset, write, reach, and container options.
--expiry default Use the default 30-day expiry. This is also the result when you omit --expiry.
--expiry until_revoked No automatic expiry.
--store <directory> Select where the CLI saves the key's local relay identity.
--json Return the server result inside a JSON data envelope.

With neither identity option, the terminal prompts for Agent nickname. Without a reach option it prompts Reach [account/container]. These prompts require an interactive terminal and human output mode. Supply every required value in scripts and with --json.

Use a nickname without spaces. The CLI accepts printable ASCII characters, requires a non-empty name before -AI, and limits the completed name to 256 bytes. New agent names end in -AI; your own account username is separate.

--write enables writes even if you also specify --preset readonly. Without --scope-json, --container-id is used only with container reach. A raw scope bypasses those scope-building options entirely, but the key label, agent identity, and expiry still apply.

Custom scope JSON

For the same read-only account reach explicitly:

glob keys create "Research helper" --agent-nickname Research --scope-json '{"version":2,"reach":{"kind":"account"},"resources":{"record":["read"]},"operations":[]}'

For a container, the reach object is { "kind": "container", "containerId": "<uuid>" }.

The accepted resource is record, with read, create, and update actions. operations must be empty. Do not add a constraints block. A scope can be valid JSON and still be refused because it requests unsupported permissions. There is no full preset or delete grant.

For a shared project, container access also requires your membership and agreement to AI access from every member. Changing the JSON cannot bypass that requirement.

Save the displayed token

Successful creation displays ONE-TIME API KEY, followed by the token. Copy it for your external tool before leaving the output. Listing keys does not reveal that token again.

The CLI also saves the key and its agent identity for running a relay. This local entry belongs to the selected store. Keep the same --store selection when you create the key and start that relay.

JSON creation results include id, token, name, agent_username, scope, created_at, and expires_at when present. Treat the token field as a secret when capturing command output.

List your keys

glob keys
glob keys list
glob keys list --json

list is the default subcommand. Human output is a tab-separated table with id, name, agent_username, frozen, created_at, expires_at, and last_used_at. Missing values show as —.

JSON data is an array of key metadata. It includes the scope as well as the table fields. Revoked keys are excluded; an expired key can still appear. Neither form returns the raw token.

Rotate a Data API key

glob keys rotate <key-uuid>
glob keys rotate <key-uuid> --store ~/glob-work --json

Supplying a key UUID replaces that key's secret while keeping its ID and scope. Save the ONE-TIME API KEY token and update each tool using it. Restart a running relay with the replacement key too.

Options are --store, --json, and --passphrase-stdin. The passphrase option is unused when you supply an API key ID. Existing local relay entries for that key are updated. If this CLI has no saved entry for the key, rotation does not reconstruct its agent identity; create the relay key on this device before relying on automatic relay setup.

The JSON response has id and token inside data.

Revoke or freeze access

glob keys revoke <key-uuid> --yes
glob keys freeze-all --yes
glob keys unfreeze-all --yes

Revocation is permanent. It also removes the selected store's saved relay entry for that key where possible. revoke accepts --store and --json.

Freeze stops access through current keys. Unfreeze re-enables eligible existing keys; expired or revoked keys remain unusable. These two commands act across the account. Both accept --json. The CLI has no per-key freeze command.

All three commands require --yes; omitting it returns CONFIRMATION_REQUIRED and exit code 2 without asking a question.

Command JSON data
revoke <id> --yes { "id": "…", "revoked": "true" }
freeze-all --yes { "frozen": "true" }
unfreeze-all --yes { "frozen": "false" }

Those result values are strings, including "true" and "false".

Sync identity generations

These commands are available in the Linux CLI:

glob keys identity
glob keys identity --json
glob keys rotate --passphrase-stdin
glob keys identity --generation 1

keys identity lists the account's generations and revocation times. Human output has generation and revoked_at columns. JSON data is an array containing generation, agreement_pk, signing_pk, and optional link_sig, created_at, and revoked_at fields. These are public identity details, rather than your private keys.

keys rotate with no positional ID rotates the sync identity. Your sync passphrase stays the same. It requires the sync passphrase through GLOB_SYNC_PASSPHRASE or --passphrase-stdin. It also accepts --store and --json. The result reports the new generation; JSON represents it as a string. If interrupted, repeat the command with the same store so it can resume its saved progress.

Rotation does not revoke the old generation automatically. To revoke an older one, run keys identity --generation <number>. A newer generation must already exist. This action runs immediately; it has no --yes option or confirmation prompt. JSON returns the revoked identity entry.

keys identity has no --store or passphrase option. On macOS, keys rotate without an ID returns UNAVAILABLE.

Recovery keys

The required-enrollment flow below is in the updated CLI source. No new CLI binary release accompanies this change; older downloads can retain the earlier optional setup and recovery-output behavior.

First encrypted-sync setup requires recovery enrollment. Run glob sync now --passphrase-stdin in an interactive terminal, save the key shown there separately from this device and type SAVED. No account envelope is published before confirmation. Cancelling creates no account keys. First setup reached through share grant or identity rotation follows the same rule.

Existing accounts without recovery keep working and can enroll later:

glob keys recovery --passphrase-stdin

You need the current sync passphrase. GLOB_SYNC_PASSPHRASE takes priority over stdin; the command has no --store option. Save the key and type SAVED before its wrap is published. The account key, passphrase, identity and document keys stay the same. Recovery keys are not stored by the CLI and cannot be revealed or replaced later. Anyone with the key and encrypted account data can open that data.

Results are added, already_present, or added_elsewhere. If another device enrolls first, discard the key just shown here and use the one saved on that device. already_present changes nothing and shows no key. An account with no sync envelope returns SYNC_KEY_FAILED (exit 6), directing you to interactive glob sync now. RECOVERY_KEY_UNSUPPORTED (exit 6) means the server refused the new wrap; it was not added.

Recovery output in scripts

Recovery keys go only to the controlling terminal, never stdout, stderr or JSON success/error output. --json, redirected output, the TUI, sync watch and relay-node cannot perform first encryption setup: RECOVERY_ENROLLMENT_REQUIRED (exit 2) directs the person to interactive glob sync now. Finish setup once, then return to the script or service. glob keys recovery --json can report already_present, but cannot add a missing recovery key noninteractively.

Existing accounts without recovery continue syncing. Human output warns with glob keys recovery; JSON sync adds recovery_enrollment_required: true, and the TUI displays the reminder. The CLI has no command for entering a recovery key to recover the sync passphrase. See account recovery.

Key command errors

Message or code Next step
Key label is required, Agent nickname is required, or --reach is required (account or container) Supply the missing argument explicitly when prompts are unavailable.
--container-id must be a UUID Use the full container UUID.
--preset must be readonly or readwrite Choose one of those presets.
--scope-json must be canonical v2 Glob Data API scope JSON Check the version, reach, resource actions, and empty operations list.
--expiry must be default or until_revoked Choose one of those two expiry modes.
active API key limit reached Revoke keys you no longer use before creating another.
CONFIGURATION_ERROR after creation or rotation The remote action may already have succeeded, but saving the local relay identity failed before the token was printed. Inspect glob keys list, resolve the storage problem, then rotate or revoke the affected key.
SYNC_FAILED with unresumable during identity rotation The saved rotation could not be resumed. Contact support before changing the store or starting another rotation elsewhere.
NOT_FOUND Check the key ID. A revoked key cannot be rotated.
AUTHENTICATION_REQUIRED Sign in again with your account session.

For external-tool access beyond these CLI commands, continue with the account API key guide.