Cowdidocs
API ReferenceContact details

List the caller's emails

GET
/v1/user/settings/emails

Returns the caller's email contacts across every organization. Includes both pending and validated emails. A user token calls this on behalf of the signed-in user.

Authorization

oauth2
AuthorizationBearer <token>

Create a client with POST /v1/oauth/clients, then exchange its credentials for an access token. AUTHORIZATION_CODE clients act on behalf of a signed-in user and always use PKCE; CLIENT_CREDENTIALS clients act as themselves. A client may only be granted scopes its creator already holds — read the grantable list from GET /v1/oauth/clients/scopes.

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/user/settings/emails"
{  "emails": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "value": "jane@example.com",      "otp": {        "step": "OWNER_AUTHORIZATION",        "sent_to": "EMAIL",        "steps": 2,        "digits": 6      },      "is_primary": true,      "validated": true,      "validated_at": "2026-01-15T09:20:00Z",      "requires_verification": true,      "verification_locked": true,      "verification_locked_at": "2026-01-20T16:45:00Z",      "created_at": "2026-09-01T10:15:30Z"    }  ]}
{  "code": "BAD_REQUEST",  "description": "Bad Request"}
{  "code": "UNAUTHORISED",  "description": "Unauthorised"}
{  "code": "FORBIDDEN",  "description": "Forbidden"}
{  "code": "RATE_LIMIT_EXCEEDED",  "description": "Too Many Requests"}
{  "code": "INTERNAL_ERROR",  "description": "Internal Server Error"}

Update the caller's profile settings PATCH

Updates the caller's global profile: the name, locale, and timezone shared across every organization the caller belongs to. Send only the fields to change; omitted fields keep their current value. Changing the first name, last name, or locale queues a sync to the identity provider. A user token calls this on behalf of the signed-in user. Returns 404 when the caller has no profile yet.

Add an email POST

Adds a global pending email to the caller's profile after recent authentication, and sends an OTP to it. Pending contacts do not reserve the identity; the first caller to verify a value wins the global claim. Five invalid OTP confirmations lock the contact until a platform admin resets it. Returns 400 when the caller already has the maximum number of email contacts. The returned `otp` tells where the OTP went. Confirm the OTP next. The first email of a caller with no primary email becomes the primary email when its verification completes. With an open current account, the account provider sends its OTPs. While the current account is pending, Cowdi sends the OTP.