use-link-identity

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Link identity

Link 身份

These commands are in beta and appear in

link-cli identity --help

without a preview flag. Use them when a service accepts Link attestations or signed user claims.

Service requests	Command	JSON field → HTTP header
A Link Agent Attestation Token (AAT), often via `WWW-Authenticate: PrivateToken`	`identity attestations pop`	`authorization` → `Authorization`
Signed claims, often via `WWW-Authenticate: Identity-Presentation`	`identity credentials present`	`presentation` → `Identity-Presentation`

An AAT proves issuance by Link without disclosing user claims. A presentation discloses selected claims and proves possession of the credential's holder key for an audience and nonce. If the service requires both, send both headers.

这些命令目前处于 测试阶段，无需 preview flag 即可在

link-cli identity --help

中看到。当服务接受 Link attestations 或 signed user claims 时，使用这些命令。

服务请求	命令	JSON 字段 → HTTP 标头
Link Agent Attestation Token (AAT)，通常通过 `WWW-Authenticate: PrivateToken` 传入	`identity attestations pop`	`authorization` → `Authorization`
Signed claims，通常通过 `WWW-Authenticate: Identity-Presentation` 传入	`identity credentials present`	`presentation` → `Identity-Presentation`

AAT 可证明由 Link 完成签发，同时不会披露用户 claims。presentation 会披露选定的 claims，并证明调用方持有与 credential 绑定的 holder key，且该证明面向指定的 audience 和 nonce。如果服务同时要求两者，请同时发送两个标头。

Setup and handling

设置与处理

For installation and authentication, reuse the create-payment-credential skill's shared guidance.

Identity commands are available through the CLI, not its MCP tools.
Only
```
request
```
needs Link authentication.
```
list
```
,
```
pop
```
, and
```
present
```
use local files. Requests return paths and metadata;
```
pop
```
and
```
present
```
return proofs.
Capture stdout with
```
--format json
```
, parse it programmatically with a JSON parser or
```
jq
```
, and pass the exact proof to the HTTP client or browser automation. Never manually transcribe, reconstruct, or re-encode tokens or presentations. Keep proofs, private keys, and claim values out of transcripts and logs; use restrictive permissions for handoff files.
Cached identity files belong to the home directory. Changing
```
--auth
```
or logging in as another user does not switch the cached identity. Use separate home directories for different users.

有关安装和身份验证，请复用 create-payment-credential skill 中的共享指南。

Identity 命令可通过 CLI 使用，但不能通过其 MCP tools 使用。
只有
```
request
```
需要 Link 身份验证。
```
list
```
、
```
pop
```
和
```
present
```
使用本地文件。
```
request
```
返回路径和元数据；
```
pop
```
和
```
present
```
返回 proofs。
使用
```
--format json
```
捕获 stdout，通过 JSON parser 或
```
jq
```
以编程方式解析，并将完全相同的 proof 传给 HTTP client 或 browser automation。**切勿手动转录、重构或重新编码 tokens 或 presentations。**不要将 proofs、private keys 和 claim values 写入 transcripts 或 logs；交接文件应使用严格限制的权限。
Cached identity 文件位于主目录。更改
```
--auth
```
或以其他用户身份登录，不会切换缓存的 identity。不同用户应使用彼此独立的主目录。

Attestations

bash

undefined

bash

undefined

Inspect inventory.

link-cli identity attestations list --format json

Refill only when needed. Count is required: 1–100.

link-cli identity attestations request --count 10 --format json

Pop a token when ready to use it.

link-cli identity attestations pop --format json


Check `errors` and `attestations`. Only entries with `storage: "pool"` are available to `pop`; `total_token_count` also includes exports. Requests append to `~/.link-cli/identity/attestations/pool.json`.

Example `pop` output:

```json
{
  "issuer": "https://api.link.com",
  "token_key_id": "<issuer-key-id>",
  "token": "<token>",
  "authorization": "PrivateToken token=\"<token-with-header-padding>\""
}

Use

authorization

verbatim, including its scheme and quoting.

pop

removes the token locally; server reuse rules belong to the service. Keep the same AAT for retries tied to an existing interaction, and use a fresh one for a new service. Do not return popped tokens to the pool.

For agent-managed allocation, export a batch instead:

bash

link-cli identity attestations request --count 10 --output-file ./aats.json --format json

Use a new file outside

~/.link-cli/identity/attestations

. Read its

tokens

array and each entry's

authorization

programmatically. Exported tokens never enter the CLI pool; the caller owns allocation, concurrency, and cleanup.

link-cli identity attestations pop --format json


检查 `errors` 和 `attestations`。只有 `storage: "pool"` 的条目可供 `pop` 使用；`total_token_count` 还包括 exports。`request` 操作会追加到 `~/.link-cli/identity/attestations/pool.json`。

`pop` 输出示例：

```json
{
  "issuer": "https://api.link.com",
  "token_key_id": "<issuer-key-id>",
  "token": "<token>",
  "authorization": "PrivateToken token=\"<token-with-header-padding>\""
}

逐字使用

authorization

，包括其 scheme 和引号。

pop

会在本地移除 token；服务端如何复用由服务决定。对于与现有 interaction 关联的重试，请使用同一个 AAT；对于新服务，请使用新的 AAT。不要将已 pop 的 tokens 放回 pool。

如需由 Agent 管理分配，请改为导出一批：

bash

link-cli identity attestations request --count 10 --output-file ./aats.json --format json

使用

~/.link-cli/identity/attestations

之外的新文件。以编程方式读取其中的

tokens

数组以及每个条目的

authorization

。导出的 tokens 永远不会进入 CLI pool；分配、并发控制和清理由调用方负责。

Credentials and presentations

Credentials 与 presentations

bash

undefined

bash

undefined

Check errors, expired, expires_at, and claim_names.

link-cli identity credentials list --format json

Request only if no usable credential exists for the intended user.

link-cli identity credentials request --format json


Issuance replaces `~/.link-cli/identity/credentials/current.json` and creates or reuses `~/.link-cli/identity/holder-key.jwk`. Keep both local. Choose claims with `present`:

```bash
link-cli identity credentials present \
  --aud 'https://service.example' \
  --nonce '<nonce-from-challenge>' \
  --claim email \
  --format json

Use the service challenge's exact audience and nonce after checking that they belong to the intended service. All three options are required. Repeat

--claim

only for additional requested claims authorized by the user's task. Pass challenge values as individual process arguments or quote them safely in a shell.

Example output:

json

{"presentation":"<issuer-jwt>~<email-disclosure>~<key-binding-jwt>"}

present

signs locally with the saved holder key and leaves the files unchanged. Send the presentation promptly. Reuse the underlying credential until expiry, but obtain a fresh challenge after a nonce is consumed or expires.

link-cli identity credentials request --format json


签发流程会替换 `~/.link-cli/identity/credentials/current.json`，并创建或复用 `~/.link-cli/identity/holder-key.jwk`。两者都应保留在本地。使用 `present` 选择 claims：

```bash
link-cli identity credentials present \
  --aud 'https://service.example' \
  --nonce '<nonce-from-challenge>' \
  --claim email \
  --format json

确认 audience 和 nonce 属于目标服务后，使用服务 challenge 中的准确 audience 和 nonce。三个选项均为必填。只有当用户任务授权请求更多 claims 时，才可重复使用

--claim

。将 challenge 值作为单独的进程参数传入，或在 shell 中安全地引用。

输出示例：

json

{"presentation":"<issuer-jwt>~<email-disclosure>~<key-binding-jwt>"}

present

使用已保存的 holder key 在本地签名，且不会更改这些文件。请尽快发送 presentation。在 credential 到期前可复用底层 credential，但如果 nonce 已被使用或过期，应获取新的 challenge。

Send and recover

发送与恢复

Set headers only for the intended endpoint. Preserve the challenged operation's method, body, session, interaction identifiers, and any required AAT. Avoid global browser headers or redirects that forward proofs to another origin. Report success only after the service accepts the request.

```
ATTESTATION_POOL_EMPTY
```
: request a batch, then pop a token.
Errors in
```
list
```
: inspect the reported file/error instead of treating storage as empty.
Unavailable claim: check
```
claim_names
```
; do not disclose extra claims or the raw credential.
Missing or mismatched holder key: preserve the files and restore the correct key or explicitly obtain a new credential.
Audience or nonce rejection: check the intended service and its current challenge before presenting again.

仅应为目标 endpoint 设置 HTTP 标头。保留受 challenge 保护操作的 HTTP method、body、session、interaction identifiers，以及任何必需的 AAT。避免使用全局 browser headers，也不要通过 redirects 将 proofs 转发到其他 origin。只有在服务接受请求后，才能报告成功。

```
ATTESTATION_POOL_EMPTY
```
：先 request 一批 attestations，再 pop 一个 token。
```
list
```
中出现错误：检查所报告的 file/error，不要将 storage 视为 empty。
claim 不可用：检查
```
claim_names
```
；不要披露额外的 claims 或原始 credential。
holder key 缺失或不匹配：保留这些文件并恢复正确的 holder key，或明确获取新的 credential。
audience 或 nonce 被拒绝：再次
```
present
```
之前，检查目标服务及其当前 challenge。