<!-- llms.txt: https://workos.com/llms.txt -->
<!-- feedback.md: https://workos.com/docs/feedback.md -->

# Credential

A credential is a website login that one user saved: a website address, a username, and a password. The API never returns the username or the password.

Users save, retry, and delete logins in the Agent Vault widget. These endpoints let your server read and delete them.

:::code-group{title="Example credential"}

```json language="curl"
{
  "id": "bcred_01JD3XB2F6H8K0M4P7R9T1V3WX",
  "service_id": "website",
  "label": "Shipping portal",
  "status": "active",
  "active_space_count": 1,
  "website_url": "https://shipping.example.com",
  "setup_state": "connected",
  "failure_reason": null,
  "last_verified_at": "2026-11-13T18:02:11.000Z",
  "retry_after": null,
  "attempt": null
}
```

:::

## Failure reasons

When `setup_state` is `needs_attention`, `failure_reason` holds one of these values.

| Reason                            | Meaning                                                               |
| --------------------------------- | --------------------------------------------------------------------- |
| `invalid_credentials`             | The website rejected the username or password.                        |
| `mfa_required`                    | The website asked for a second factor that could not be completed.    |
| `captcha`                         | The website showed a CAPTCHA that could not be solved.                |
| `unsupported_authentication`      | The website uses a sign-in method Agent Vault does not support.       |
| `different_login_origin_required` | The website signs users in on a different origin from the one saved.  |
| `website_unavailable`             | The website could not be reached.                                     |
| `login_flow_changed`              | The website's sign-in page changed since the login last worked.       |
| `verification_inconclusive`       | WorkOS could not confirm that the sign-in worked.                     |
| `provider_unavailable`            | The browser could not be started or reached.                          |
| `budget_exceeded`                 | The sign-in used up its allowed attempts.                             |
| `deadline_exceeded`               | The sign-in did not finish in time.                                   |
| `unsupported_policy`              | The website is not one Agent Vault can sign in to.                    |
| `authorization_revoked`           | The user's session ended or access was revoked while the sign-in ran. |
| `credential_replaced`             | The login's details were replaced while the sign-in ran.              |
| `cancelled`                       | The sign-in was canceled.                                             |

## Delete a credential

Deletes a saved login. Every Space that is signed in with it is revoked at once, so an agent using one of them loses access.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request DELETE \
  --url "https://api.workos.com/agent-vault/credentials/bcred_01JD3XB2F6H8K0M4P7R9T1V3WX?user_id=user_01E4ZCR3C56J083X43JQXF3JK5&organization_id=org_01EHZNVPK3SFK441A1RGBFSHRT" \
  --header "Authorization: Bearer sk_example_123456789"
```

```json language="json" title="Response" tab="2"
{
  "id": "bcred_01JD3XB2F6H8K0M4P7R9T1V3WX",
  "status": "revoked",
  "revoked_space_ids": ["bspace_01JD3X9W4Q5Z8R7T6Y2N0M1KBC"],
  "cleanup_status": "pending"
}
```

:::

### Error responses

- **401 Unauthorized**: the user is not in the environment of the API key, or is not an active member of the organization.
- **403 Forbidden**: the login does not belong to the user, or it was already deleted.

## List credentials

Lists the logins a user saved in an organization.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request GET \
  --url "https://api.workos.com/agent-vault/credentials?user_id=user_01E4ZCR3C56J083X43JQXF3JK5&organization_id=org_01EHZNVPK3SFK441A1RGBFSHRT" \
  --header "Authorization: Bearer sk_example_123456789"
```

```json language="json" title="Response" tab="2"
{
  "object": "list",
  "data": [
    {
      "id": "bcred_01JD3XB2F6H8K0M4P7R9T1V3WX",
      "service_id": "website",
      "label": "Shipping portal",
      "status": "active",
      "active_space_count": 1,
      "website_url": "https://shipping.example.com",
      "setup_state": "connected",
      "failure_reason": null,
      "last_verified_at": "2026-11-13T18:02:11.000Z",
      "retry_after": null,
      "attempt": null
    }
  ]
}
```

:::

### Error responses

- **401 Unauthorized**: the user is not in the environment of the API key, or is not an active member of the organization.

### credential

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier of the saved login. |
| `service_id` | string | Yes | The kind of service the login is for. A login saved with a website address has `website`. |
| `label` | string | Yes | The name the saved login is shown with. |
| `status` | "active" \| "revoked" | Yes | Whether the saved login can be used. A `revoked` login was deleted. |
| `active_space_count` | integer | Yes | The number of open Spaces that are signed in with this login. |
| `website_url` | string | No | The address of the website the login is for. |
| `setup_state` | "pending" \| "connecting" \| "connected" \| "needs_attention" | Yes | Where the saved login's latest sign-in stands. `pending`: the login is saved and its sign-in has not started. `connecting`: WorkOS is signing in to the website. `connected`: the latest sign-in worked. An agent can use the login. `needs_attention`: the latest sign-in failed. See `failure_reason`. |
| `failure_reason` | string | No | Why the latest sign-in failed, or `null` when it did not. |
| `last_verified_at` | string | No | ISO 8601 timestamp of the last sign-in that worked, or `null`. |
| `retry_after` | string | No | ISO 8601 timestamp before which a new sign-in can't start, or `null`. |
| `attempt` | object | No | The sign-in that is running for this login, or `null` when none is. |

### DELETE /agent-vault/credentials/{id}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier of the saved login. |
| `user_id` | string | Yes | agent_vault_delegation.user_id_query |
| `organization_id` | string | No | agent_vault_delegation.organization_id_query |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Unique identifier of the deleted login. |
| `status` | "revoked" | Always `revoked`. |
| `revoked_space_ids` | string[] | IDs of the Spaces that were signed in with the login. Each one is revoked. |
| `cleanup_status` | "pending" \| "completed" | Whether the browsers of those Spaces have shut down. |

### GET /agent-vault/credentials

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | string | Yes | agent_vault_delegation.user_id_query |
| `organization_id` | string | No | agent_vault_delegation.organization_id_query |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `object` | "list" | Indicates this is a list response. |
| `data` | object[] | Array of the user's [credentials](/reference/agent-vault/credential). |