Connect a machine or agent

A remote client uses https://app.asyncflux.com/api/secrets with a workspace API token. Have a human workspace owner or admin create a token for this machine under Settings → API tokens. Choose Read metadata (secrets:read) initially; add Read secret values (secrets:values) only when authorized and needed.

Use a separate token for each laptop, integration or agent. The token selects one workspace and applies to all its environments. Its actor's live role and membership also limit access.

Store the credential

Save the token through your machine's credential manager or deployment secret mechanism. Supply it as VIKINGS_TOKEN only to the process making the request. Do not put a literal token in a shell command, repository file, agent prompt or shared transcript. Disable shell tracing; environment variables pass to child processes, so use a dedicated shell and clear the variable afterward.

The commands below assume the credential mechanism has already populated VIKINGS_TOKEN. They require Bash, curl and jq. No example token in this documentation is usable.

Check authentication

set +x
set -o pipefail
: "${VIKINGS_TOKEN:?Load the API token from your credential manager first}"
printf 'header = "Authorization: Bearer %s"\n' "$VIKINGS_TOKEN" \
  | curl --config - --fail --silent --show-error \
      'https://app.asyncflux.com/api/work/auth/token-self' \
  | jq '{id, name, workspace_id, scopes, status, expires_at}'

The response describes this token and does not return its secret. Confirm the workspace ID and selected scopes. A token cannot create more tokens or download the agent skill through the human management endpoints.

List metadata

printf 'header = "Authorization: Bearer %s"\n' "$VIKINGS_TOKEN" \
  | curl --config - --fail --silent --show-error \
      'https://app.asyncflux.com/api/secrets/envs/dev/secrets' \
  | jq '{workspace, env, secrets: [.secrets[] | {name, type, version}]}'
unset VIKINGS_TOKEN

This filter deliberately excludes display values and notes. The raw metadata response may contain full publishable, certificate and config values. Use GET /api/secrets/workspace to discover environments.

You normally do not need a workspace header for a token request. If you provide X-Vikings-Workspace, use the token's workspace ID, not its slug; it cannot select another workspace.

Install the agent instructions

A signed-in owner/admin can use Download agent skill under Settings → API tokens → Connect a machine or agent. Review the downloaded SKILL.md, then install it through your agent's skill installation workflow on each client machine. For manual installs, use ~/.codex/skills/asyncflux-secrets/SKILL.md for Codex or ~/.claude/skills/asyncflux-secrets/SKILL.md for Claude.

The skill contains instructions, not a credential. Downloading it or registering it in a Library catalog does not provision a token or install it on another machine. Keep the token in the credential manager and pass the agent its locator, required task and intended environment.

Retrieve a value deliberately

Use POST /api/secrets/envs/dev/secrets/DOCS_EXAMPLE_TOKEN/reveal with JSON body {} and Content-Type: application/json when the task needs that named value. This requires secrets:values and an owner/admin actor. Send the response directly to the consuming process or an access-restricted temporary file, and remove the temporary copy promptly. The API reference defines the response.

The host's secrets CLI is for its local Unix socket. It is not a remote HTTPS client. Running secrets init or secrets serve on a laptop creates or serves a different local store; it does not connect the laptop to the central store.

For failures, diagnose the HTTP status and reachability from this machine. See Troubleshooting; a successful request from another machine is not proof this one can connect.