Create or attach a wallet user
Creates a wallet user, or attaches one to an identity you already have.
/v1/usersCreates a wallet user, or attaches one to an identity you already have. Requires users:write. external_id is your own identifier and is what makes this call safe to repeat: a second create with the same external_id is refused user_exists (409) rather than opening a second wallet. A missing body or a field outside its bounds gives invalid_request (400).
Authorization
bearerAuth A tenant API key (sk_{env}_{id}_{secret}), a wallet user token, or an IdP access token. Which principal the credential resolves to decides the scopes it carries; see the authentication guide.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
curl -sS -X POST "$WALLETD_API/v1/users" \ -H "Authorization: Bearer $WALLETD_API_KEY" \ -H "Content-Type: application/json" \ -d '{"external_id": "user-42", "kind": "consumer", "handle": "ada"}'{ "id": "0191c2d4-8f3a-7c51-9b2e-4a6f8d310e27", "external_id": "user-42", "kind": "consumer", "handle": "ada", "status": "active", "created_at": "2026-09-20T09:14:22Z"}