---
title: Connect a machine or agent
description: Authenticate a remote client and inspect metadata without printing protected values.
---

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](https://app.asyncflux.com/#/settings/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

```bash
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

```bash
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](api.md#reveal-a-value) 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](troubleshooting.md); a successful request from another machine is not proof this one can connect.