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.
Example credential
cURL
credential
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. |
Lists the logins a user saved in an organization.
cURL
| 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" |
| { | |
| "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 | |
| } | |
| ] | |
| } |
GET/agent-vault /credentials
Parameters
Returns object
- 401 Unauthorized: the user is not in the environment of the API key, or is not an active member of the organization.
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.
cURL
| 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" |
| { | |
| "id": "bcred_01JD3XB2F6H8K0M4P7R9T1V3WX", | |
| "status": "revoked", | |
| "revoked_space_ids": ["bspace_01JD3X9W4Q5Z8R7T6Y2N0M1KBC"], | |
| "cleanup_status": "pending" | |
| } |
DELETE/agent-vault /credentials /:id
Parameters
Returns object
- 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.