> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wirebox.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Vault Access

> Grant, list, and revoke an agent identity's access to a vault secret.

Access grants link a secret to an agent identity. An identity-scoped key with
the `vault:read` scope can read a secret only if it has a grant. The server
enforces this by filtering ciphertext per identity on unlock, so revocation
takes effect on the next unlock. All access operations are admin-only.

### Path Parameters

<ParamField path="secret_id" type="string" required>
  The secret's id (`vsec_` prefix).
</ParamField>

### Operations

| Method & Path | Description |
| :- | :- |
| `GET /api/v1/vault/secrets/{secret_id}/access` | List identities granted access. |
| `POST /api/v1/vault/secrets/{secret_id}/access` | Grant access. Body: `identity_id`. |
| `DELETE /api/v1/vault/secrets/{secret_id}/access/{identity_id}` | Revoke access. |

### Access Grant Object

<ResponseField name="id" type="string">
  Grant identifier (`vacc_` prefix).
</ResponseField>

<ResponseField name="secret_id" type="string">
  The secret the grant applies to.
</ResponseField>

<ResponseField name="identity_id" type="string">
  The agent identity (`agt_` prefix) that was granted access.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

<RequestExample>
  ```python Python theme={null}
  eva = wb.get_identity("eva")
  wb.vault.grant_access("vsec_01J8ABC123XYZ", eva.id)
  wb.vault.list_access("vsec_01J8ABC123XYZ")
  wb.vault.revoke_access("vsec_01J8ABC123XYZ", eva.id)
  ```

  ```ts TypeScript theme={null}
  const eva = await wb.getIdentity("eva");
  await wb.vault.grantAccess("vsec_01J8ABC123XYZ", eva.id);
  await wb.vault.listAccess("vsec_01J8ABC123XYZ");
  await wb.vault.revokeAccess("vsec_01J8ABC123XYZ", eva.id);
  ```

  ```bash CLI theme={null}
  # Accepts an agent handle (@eva) or id, and a secret name or id.
  wirebox vault access grant GitHub -i @eva
  wirebox vault access list GitHub
  wirebox vault access revoke GitHub -i @eva
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.wirebox.sh/api/v1/vault/secrets/vsec_01J8ABC123XYZ/access \
    -H "Authorization: Bearer $WIREBOX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "identity_id": "agt_01J8ABC123XYZ" }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": "vacc_01J8ABC123XYZ",
    "secret_id": "vsec_01J8ABC123XYZ",
    "identity_id": "agt_01J8ABC123XYZ",
    "created_at": "2026-10-10T10:00:00Z"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.