> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcard.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Disconnect a user
> End your app's connection to a user. Your app can no longer read their cards or ask them to pay.
Call it when the user asks your app to forget them. Every token your app holds for the user stops working, links you sent them stop opening, and the user's cards stay in their Vault.
```bash cURL theme={null}
curl -X DELETE https://api.agentcard.sh/api/v2/vault_users/usr_8f3k2m/connection \
-H "Authorization: Bearer $ORG_TOKEN"
```
```json 200 theme={null}
{
"object": "vault_user_connection",
"user_id": "usr_8f3k2m",
"connected": false,
"revoked_tokens": 2,
"revoked_wallet_links": 0,
"revoked_sessions": 1,
"test_mode": false
}
```
After the call, [List a user's vaulted cards](/api-reference/vault/cards-list) answers `404 connection_not_found` for the user, and a checkout authorization for them is refused. To work with the user again, send them a new [vault session](/api-reference/vault/sessions-create).
Call it as often as you like. A second call answers `200` with every count at `0`.
## Errors
A user your app never connected is refused, so the call tells you nothing about anyone else's users:
```text theme={null}
HTTP 404
{
"error": {
"code": "connection_not_found",
"message": "No production connection exists for that user under this client.",
"docs": "https://docs.agentcard.sh"
}
}
```
The tokens stop working before the user's auto-approval for your app does. While the second half is still in flight, the call answers:
```text theme={null}
HTTP 503
{
"error": {
"code": "partner_disconnect_pending",
"message": "The connection is off. The payment authority has not confirmed yet: call again to check.",
"docs": "https://docs.agentcard.sh"
}
}
```
| Code | Meaning | What to do |
| - | - | - |
| `404 connection_not_found` | Your app holds no connection to that user in this mode. | Check the `user_id`, and that you called with the token of the mode the user connected in. |
| `503 partner_disconnect_pending` | The tokens are off. The user's auto-approval for your app is not yet. | Call again until it answers `200`. The tokens stay off either way. |
Deleting one vault session with `DELETE /api/v2/vault_sessions/{id}` ends only that link and the token it gave you. The user stays connected to your app.
## OpenAPI
````yaml openapi.json DELETE /api/v2/vault_users/{user_id}/connection
openapi: 3.1.0
info:
title: Agentcard API
version: 2.0.0
description: >-
The Agentcard v2 API — connect your users and verify their identity from
your own backend. Every call is authenticated with a platform access token
minted from your `client_id` + `client_secret`.
servers:
- url: https://api.agentcard.sh
description: >-
There is one base URL. Sandbox vs production is decided by the client
credential you use, never by the host.
security:
- platformToken: []
tags:
- name: Authentication
description: >-
Exchange your client credentials for a platform access token, and
introspect what a token acts as.
- name: Connect
description: >-
Connect a user to your platform: send a one-time code, verify it, record
consent, and keep the connection alive.
- name: Identity verification
description: >-
Verify a connected user's identity: upload their ID, submit any extra
fields we ask for, then show a short face scan.
paths:
/api/v2/vault_users/{user_id}/connection:
delete:
tags:
- Connect
summary: Disconnect a user
description: >-
Ends your app's connection to a user. Every token your app holds for the
user stops working, Vault session links they have not opened stop
opening, and their cards stay in their Vault. Idempotent: a second call
answers `200` with every count at `0`.
operationId: vaultUserConnectionDelete
parameters:
- name: user_id
in: path
required: true
description: The user's id, as your app stored it when they connected.
schema:
type: string
maxLength: 64
responses:
'200':
description: The user is disconnected from your app.
content:
application/json:
schema:
type: object
properties:
object:
type: string
enum:
- vault_user_connection
user_id:
type: string
connected:
type: boolean
enum:
- false
revoked_tokens:
type: integer
description: >-
Tokens your app held for the user that stopped working on
this call.
revoked_wallet_links:
type: integer
description: >-
Wallet links your app sent the user that stopped working
on this call.
revoked_sessions:
type: integer
description: >-
Vault session links the user had not opened yet. A
disconnected user who taps one gets nothing.
test_mode:
type: boolean
example:
object: vault_user_connection
user_id: usr_8f3k2m
connected: false
revoked_tokens: 2
revoked_wallet_links: 0
revoked_sessions: 1
test_mode: false
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: >-
`connection_not_found`: your app holds no connection to that user in
this mode.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: >-
`partner_disconnect_pending`: the tokens are off, and the user's
auto-approval for your app is not yet. Call again until it answers
`200`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
responses:
Unauthorized:
description: >-
`unauthorized` — the platform access token is missing or expired.
Exchange your client credentials for a fresh one.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
description: Every v2 error uses the same envelope.
properties:
error:
type: object
properties:
code:
type: string
description: A stable, machine-readable string (snake_case). Branch on this.
message:
type: string
description: A human-readable explanation, safe to log.
docs:
type: string
description: A link back to the reference.
field_errors:
type: object
additionalProperties:
type: string
description: Only on `invalid_fields` — names each field to fix.
warnings:
type: array
items:
type: string
description: >-
Only on document upload errors — actionable feedback safe to
show the user.
securitySchemes:
platformToken:
type: http
scheme: bearer
description: >-
A platform access token. Get one on the **Create an access token**
endpoint by exchanging your `client_id` + `client_secret`, then send it
as `Authorization: Bearer `. Tokens live one hour.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.