--- updatedAt: 2026-06-04T19:58:43.000Z agentTools: projectIndex: https://docs.wristband.dev/llms.txt --- # Patch User Patches the specified user. ### Required Permissions Below is the list of required permissions needed to interact with this API. For each permission, the allowed permission boundaries are also specified. | Permission | Boundary | Description | | --------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | **user:update** | Application | The subject can update all users under the application to which the subject belongs. | | | Tenant | The subject can update all users associated with the tenant to which the subject belongs. | | | Tenant Inclusion List | The subject can update all users associated with tenants specified in the tenant inclusion list. | | | Tenant Exclusion List | The subject can update all users associated with tenants in the subject's application who are not on the tenant exclusion list. | | | Self | A user subject can update itself. | ### Field-Level Permissions In addition to the permissions above, the following permissions are required conditionally based on the fields being updated. The permission boundaries that apply to the `user:update` permission also apply to the field-level permissions. | Permission | Description | | ----------------------------------- | --------------------------------------------------------------- | | **user:manage-email** | Required if the `email` or `emailVerified` fields are modified. | | **user:manage-external-id** | Required if the `externalId` field is modified. | | **user:manage-restricted-metadata** | Required if the `restrictedMetadata` field is modified. | | **user:manage-status** | required if the `status` field is modified. | # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Resource Management APIs", "version": "1.0.0", "description": "Resource Management APIs", "license": { "name": "Private", "url": "https://wristband.dev/terms/" }, "termsOfService": "https://wristband.dev/terms/", "contact": { "name": "Wristband Support", "email": "support@wristband.dev", "url": "https://wristband.dev/contact/" } }, "servers": [ { "url": "https://{application_vanity_domain}", "description": "Wristband application scoped URL.", "variables": { "application_vanity_domain": { "default": "yourapp-yourorg.us.wristband.dev", "description": "Wristband vanity domain scoped to a specific application." } } } ], "tags": [ { "name": "Users", "description": "Users", "x-displayName": "Users" } ], "paths": { "/api/v1/users/{userId}": { "parameters": [ { "$ref": "#/components/parameters/Resource_Management_APIs_UserId" } ], "patch": { "summary": "Patch User", "operationId": "patchUserV1", "tags": [ "Users" ], "parameters": [ { "$ref": "#/components/parameters/Resource_Management_APIs_If-Match" }, { "$ref": "#/components/parameters/Resource_Management_APIs_ReplaceCustomMetadata" } ], "requestBody": { "description": "User patch request adhering to the JSON Merge Patch specification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource_Management_APIs_User" }, "examples": { "Example 1": { "value": { "username": "user1", "email": "mike@fake.com", "emailVerified": true, "externalId": "externalId", "givenName": "Mike", "familyName": "Smith", "middleName": "Ken", "honorificPrefix": "Dr.", "honorificSuffix": "Jr.", "nickname": "Mikey", "preferredLanguage": "en-US", "locale": "en-AU", "timeZone": "America/Los_Angeles", "restrictedMetadata": { "fieldA": "a", "fieldB": { "fieldC": "c" } }, "publicMetadata": { "fieldA": "a", "fieldB": { "fieldC": "c" } }, "status": "ACTIVE" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "ETag": { "$ref": "#/components/headers/Resource_Management_APIs_ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource_Management_APIs_User" }, "examples": { "Example 1": { "$ref": "#/components/examples/Resource_Management_APIs_User" } } } } }, "400": { "$ref": "#/components/responses/Resource_Management_APIs_400-with-message-body" }, "401": { "$ref": "#/components/responses/Resource_Management_APIs_401" }, "403": { "$ref": "#/components/responses/Resource_Management_APIs_403" }, "404": { "$ref": "#/components/responses/Resource_Management_APIs_404-user-not-found" }, "405": { "$ref": "#/components/responses/Resource_Management_APIs_405" }, "406": { "$ref": "#/components/responses/Resource_Management_APIs_406" }, "409": { "$ref": "#/components/responses/Resource_Management_APIs_409-modification-conflict" }, "412": { "$ref": "#/components/responses/Resource_Management_APIs_412" }, "415": { "$ref": "#/components/responses/Resource_Management_APIs_415" }, "500": { "$ref": "#/components/responses/Resource_Management_APIs_500" }, "503": { "$ref": "#/components/responses/Resource_Management_APIs_503" } }, "security": [ { "Resource_Management_APIs_BearerAuth": [] } ] } } }, "components": { "securitySchemes": { "Resource_Management_APIs_BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "parameters": { "Resource_Management_APIs_If-Match": { "name": "If-Match", "description": "Used to perform a conditional update", "in": "header", "required": false, "schema": { "type": "string", "example": "1", "minLength": 1 } }, "Resource_Management_APIs_UserId": { "name": "userId", "description": "User Id", "in": "path", "required": true, "schema": { "type": "string", "example": "jayovsssgbgbpk47ihblujcm2e", "minLength": 1, "maxLength": 26 } }, "Resource_Management_APIs_ReplaceCustomMetadata": { "name": "replace_custom_metadata", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Boolean indicating whether the custom metadata fields will be updated using a full replace instead of performing a JSON merge patch. If set to `true` then the custom metadata fields will be updated using a full replace; otherwise a JSON merge patch will be performed." } }, "schemas": { "Resource_Management_APIs_id": { "type": "string", "minLength": 1, "maxLength": 26, "example": "pl4a4aa4jzydksmrf3jnu5yfcw", "description": "Globally unique Id of the resource.", "readOnly": true }, "Resource_Management_APIs_activation-metadata": { "title": "ActivationMetadata", "type": "object", "description": "Activation metadata associated to a resource.", "properties": { "version": { "type": "string", "example": "1.0", "description": "The version of the resource", "readOnly": true }, "lastModifiedTime": { "type": "string", "format": "date-time", "example": "2016-06-13T19:49:31.686Z", "description": "The time at which the resource was last modified", "readOnly": true }, "creationTime": { "type": "string", "format": "date-time", "example": "2016-06-13T19:49:31.686Z", "description": "The time at which the resource was created", "readOnly": true }, "activationTime": { "type": "string", "format": "date-time", "example": "2016-06-13T19:49:31.686Z", "description": "The time at which the resource was activated. This vaue will only be present if the entity has an active status.", "readOnly": true }, "deactivationTime": { "type": "string", "format": "date-time", "example": "2016-06-13T19:49:31.686Z", "description": "The time at which the resource was deactivated. This vaue will only be present if the entity has an inactive status.", "readOnly": true } } }, "Resource_Management_APIs_api-error": { "title": "ApiError", "type": "object", "description": "API error object", "x-examples": { "Example 1": { "code": "invalid_request", "message": "The request was invalid", "ticket": "11t7n71hi5e6t" } }, "properties": { "type": { "type": "string", "example": "base_error", "minLength": 1, "description": "The type of the API error.", "readOnly": true }, "code": { "type": "string", "example": "invalid_request", "minLength": 1, "description": "A code identifying the error that occurred.", "readOnly": true }, "message": { "type": "string", "example": "The request was invalid", "description": "A free text message describing the error. This error message is only meant to help developers understand the cause of the error. It should not be used for programmatic purposes.", "readOnly": true }, "ticket": { "type": "string", "example": "11t7n71hi5e6t", "description": "Ticket that can help correlate the error to the backend", "readOnly": true }, "details": { "type": "object", "description": "A map of details about the error. The keys are defined by the API.", "additionalProperties": {}, "example": { "attemptsRemaining": 4 } } }, "required": [ "type", "code" ] }, "Resource_Management_APIs_constraint-violations-api-error": { "title": "ConstraintViolationsApiError", "description": "An API error that occurred due to a constraint violation", "allOf": [ { "$ref": "#/components/schemas/Resource_Management_APIs_api-error" }, { "type": "object", "readOnly": true, "required": [ "violations" ], "properties": { "violations": { "type": "object", "readOnly": true, "required": [ "code" ], "properties": { "code": { "type": "string", "description": "A code identifying the constraint violation.", "minLength": 1, "example": "too_long" }, "constraintAttributes": { "type": "object", "description": "A map of constraint attribute values.", "additionalProperties": { "type": "string" }, "example": { "maxLength": "10" } } } } } } ], "x-examples": { "Example 1": { "type": "constraint_violations_error", "code": "message_body_constraint_violations", "message": "The request contained invalid fields", "ticket": "11t7n71hi5e6t", "violations": { "field1": { "code": "too_long", "constraintAttributes": { "maxLength": "10" } }, "field2": { "code": "not_null" } } } } }, "Resource_Management_APIs_User": { "title": "User", "type": "object", "description": "User", "x-tags": [ "Models" ], "properties": { "id": { "$ref": "#/components/schemas/Resource_Management_APIs_id" }, "tenantId": { "type": "string", "example": "x63nnomvwrgqhgd2ofpdt3uk5e", "minLength": 1, "maxLength": 26, "description": "ID of the tenant that the user belongs to. For multi-tenant applications this value is required on create." }, "applicationId": { "type": "string", "example": "x73uqlzuujghvfunxy6kez4wlm", "minLength": 1, "maxLength": 26, "description": "ID of the application that the user belongs to.", "readOnly": true }, "identityProviderName": { "type": "string", "example": "wristband", "minLength": 1, "maxLength": 70, "description": "[Required on Create] Name of the identity provider that the user belongs to." }, "identityProviderType": { "type": "string", "example": "WRISTBAND", "minLength": 1, "maxLength": 25, "enum": [ "WRISTBAND", "APPLE", "BITBUCKET", "CUSTOM", "GITHUB", "GITLAB", "GOOGLE", "GOOGLE_WORKSPACE", "MICROSOFT", "MICROSOFT_ENTRA_ID", "OKTA" ], "description": "Type of the identity provider that the user belongs to.", "readOnly": true }, "username": { "type": "string", "example": "user1", "minLength": 1, "maxLength": 200, "description": "A unique identifier that can be used in conjunction with a password to authenticate a user." }, "hasPassword": { "type": "boolean", "example": true, "description": "Boolean indicating whether the user has a password set or not.", "readOnly": true }, "email": { "type": "string", "format": "email", "example": "mike@fake.com", "minLength": 1, "maxLength": 200, "description": "[Required on Create] Primary email address of the user. This is the email that all transactional emails will be sent to." }, "emailVerified": { "type": "boolean", "description": "Boolean indicating if the user's email has been verified or not", "default": false }, "externalId": { "type": "string", "example": "externalId", "minLength": 1, "maxLength": 200, "description": "Identifier of a user that is maintained in an external system. This value is required for users that belong to an external IdP." }, "fullName": { "type": "string", "example": "Mr. Mike Smith Jr.", "minLength": 1, "description": "The user’s full name, including all middle names, titles, and suffixes as appropriate, formatted for display (e.g., \"Ms. Barbara Jane Jensen, III”).", "maxLength": 200 }, "givenName": { "type": "string", "example": "Mike", "minLength": 1, "description": "Given name", "maxLength": 100 }, "familyName": { "type": "string", "example": "Smith", "minLength": 1, "maxLength": 100, "description": "Family name" }, "middleName": { "type": "string", "example": "Ken", "minLength": 1, "maxLength": 100, "description": "Middle name" }, "honorificPrefix": { "type": "string", "example": "Dr.", "minLength": 1, "maxLength": 40, "description": "Honorific prefix" }, "honorificSuffix": { "type": "string", "example": "Jr.", "minLength": 1, "maxLength": 40, "description": "Honorific suffix" }, "nickname": { "type": "string", "example": "Mikey", "minLength": 1, "maxLength": 100, "description": "The user's nickname" }, "displayName": { "type": "string", "example": "m.smith", "minLength": 1, "description": "The primary textual label by which this user is normally displayed by the service provider when presenting it to end-users.", "maxLength": 100 }, "pictureUrl": { "type": "string", "example": "http://image.com/my/picture.png", "minLength": 1, "description": "URL of the user’s profile picture. This URL MUST refer to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a web page containing an image. Note that this URL SHOULD specifically reference a profile photo of the user suitable for displaying when describing the user, rather than an arbitrary photo taken by the user.", "maxLength": 2000, "format": "uri" }, "gender": { "type": "string", "example": "male", "minLength": 1, "description": "The user’s gender as described by the user.", "maxLength": 100 }, "birthdate": { "type": "string", "example": "1999-03-29", "minLength": 1, "description": "The user's birthday represented in ISO 8601 YYYY-MM-DD format.", "maxLength": 10, "format": "date" }, "phoneNumber": { "type": "string", "example": "+16045551234;ext=5678", "minLength": 1, "maxLength": 50, "description": "User's preferred telephone number. The value should be normalized to E.164 format. If the phone number contains an extension, the extension should be represented using the RFC 3966 extension syntax, for example, +16045551234;ext=5678." }, "preferredLanguage": { "type": "string", "example": "en-US", "minLength": 1, "maxLength": 50, "description": "The preferred language of the user." }, "locale": { "type": "string", "example": "en-AU", "minLength": 1, "maxLength": 50, "description": "The locale used to determine how localized content such as currency, date time format, numerical representations, etc. should be rendered." }, "timeZone": { "type": "string", "example": "America/Los_Angeles", "minLength": 1, "maxLength": 50, "description": "The user's timezone" }, "restrictedMetadata": { "type": "object", "additionalProperties": true, "description": "Allows for storing custom metadata that should only be modifiable by authenticated subjects with the `user:manage-restricted-metadata` permission. Conceptually, the restricted metadata is meant to store custom attributes that end users should not be able to modify, for example, internal identifiers. The following restrictions apply to this field:\n- The max size of the JSON is 4KB\n- The max nesting depth is 3\n- The max number of top level fields within an object is 15\n- Field names must abide by the following regex: `^[a-zA-Z]([-_]?[a-zA-Z0-9]+)*$`\n- Directly nesting arrays within each other is not permitted. For example the following value is not allowed: `[[1, 2], [4,5]]`\nThe object fields are case-insensitive and if duplicate field names are provided then the last value written will win.\n\nFields can be deleted by assigning them a value of `null`. Likewise, all fields can be deleted by setting the `restrictedMetadata` field to `null`.", "default": {}, "example": { "fieldA": "a", "fieldB": { "fieldC": "c" } } }, "publicMetadata": { "type": "object", "additionalProperties": true, "description": "Allows for storing custom metadata that should be modifiable by end users. Unlike the `restrictedMetadata` field, the public metadata does not require any extra permissions to modify. The following restrictions apply to this field:\n- The max size of the JSON is 4KB\n- The max nesting depth is 3\n- The max number of top level fields within an object is 15\n- Field names must abide by the following regex: `^[a-zA-Z]([-_]?[a-zA-Z0-9]+)*$`\n- Directly nesting arrays within each other is not permitted. For example the following value is not allowed: `[[1, 2], [4,5]]`\nThe object fields are case-insensitive and if duplicate field names are provided then the last value written will win.\n\nFields can be deleted by assigning them a value of `null`. Likewise, all fields can be deleted by setting the `publicMetadata` field to `null`.", "default": {}, "example": { "fieldA": "a", "fieldB": { "fieldC": "c" } } }, "status": { "type": "string", "enum": [ "PROVISIONED", "PENDING_INVITE_ACTIVATION", "PENDING_SIGNUP_ACTIVATION", "ACTIVE", "INACTIVE" ], "default": "ACTIVE", "example": "ACTIVE", "minLength": 1, "maxLength": 45, "description": "The user's current status" }, "metadata": { "$ref": "#/components/schemas/Resource_Management_APIs_activation-metadata" } }, "example": { "tenantId": "x63nnomvwrgqhgd2ofpdt3uk5e", "identityProviderName": "wristband", "identityProviderType": "WRISTBAND", "username": "user1", "email": "mike@fake.com", "emailVerified": true, "externalId": "externalId", "fullName": "Dr. Mike Ken Smith Jr.", "givenName": "Mike", "familyName": "Smith", "middleName": "Ken", "honorificPrefix": "Dr.", "honorificSuffix": "Jr.", "nickname": "Mikey", "displayName": "m.smith", "pictureUrl": "https://image.com/my/picture.png", "gender": "male", "birthdate": "1999-03-29", "phoneNumber": "+16045551234", "preferredLanguage": "en-US", "locale": "en-AU", "timeZone": "America/Los_Angeles", "restrictedMetadata": { "fieldA": "a", "fieldB": { "fieldC": "c" } }, "publicMetadata": { "fieldA": "a", "fieldB": { "fieldC": "c" } }, "status": "ACTIVE" } } }, "examples": { "Resource_Management_APIs_User": { "description": "User JSON object.", "value": { "id": "jayovsssgbgbpk47ihblujcm2e", "tenantId": "x63nnomvwrgqhgd2ofpdt3uk5e", "applicationId": "x73uqlzuujghvfunxy6kez4wlm", "identityProviderName": "wristband", "identityProviderType": "WRISTBAND", "username": "user1", "hasPassword": true, "email": "mike@fake.com", "emailVerified": true, "externalId": "externalId", "fullName": "Dr. Mike Ken Smith Jr.", "givenName": "Mike", "familyName": "Smith", "middleName": "Ken", "honorificPrefix": "Dr.", "honorificSuffix": "Jr.", "nickname": "Mikey", "displayName": "m.smith", "pictureUrl": "https://image.com/my/picture.png", "gender": "male", "birthdate": "1999-03-29", "phoneNumber": "+16045551234", "preferredLanguage": "en-US", "locale": "en-AU", "timeZone": "America/Los_Angeles", "restrictedMetadata": { "fieldA": "a", "fieldB": { "fieldC": "c" } }, "publicMetadata": { "fieldA": "a", "fieldB": { "fieldC": "c" } }, "status": "ACTIVE", "metadata": { "version": "0.0", "lastModifiedTime": "2021-06-13T19:49:31.686Z", "creationTime": "2021-06-13T19:49:31.686Z", "activationTime": "2021-06-13T19:49:31.686Z", "deactivationTime": "2021-06-13T19:49:31.686Z" } } } }, "headers": { "Resource_Management_APIs_ETag": { "schema": { "type": "string", "example": "1.0", "minLength": 1 }, "description": "The version of the resource" } }, "responses": { "Resource_Management_APIs_401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "description": "Includes details on the failed authentication condition. This header is set in accordance with the [OAuth2 specification](https://datatracker.ietf.org/doc/html/rfc6750#section-3).", "schema": { "type": "string", "example": "Bearer error=\"invalid_token\", error_description=\"The provided access token was invalid\"" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource_Management_APIs_api-error" }, "examples": { "code - unauthenticated": { "value": { "type": "base_error", "code": "invalid_access_token", "message": "The provided access token was invalid", "ticket": "1u0d0edhwbjsd" } } } } } }, "Resource_Management_APIs_403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource_Management_APIs_api-error" }, "examples": { "code - unauthorized": { "value": { "type": "base_error", "code": "unauthorized", "message": "The request failed authorization", "ticket": "11t7n71hi5e6t" } } } } } }, "Resource_Management_APIs_405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource_Management_APIs_api-error" }, "examples": { "code - method_not_supported": { "value": { "type": "base_error", "code": "method_not_supported", "message": "The specified HTTP method is not supported", "ticket": "11t7n71hi5e6t" } } } } } }, "Resource_Management_APIs_406": { "description": "Not Acceptable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource_Management_APIs_api-error" }, "examples": { "code - not_acceptable": { "value": { "type": "base_error", "code": "not_acceptable", "message": "The Accept header was invalid", "ticket": "11t7n71hi5e6t" } } } } } }, "Resource_Management_APIs_412": { "description": "Precondition Failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource_Management_APIs_api-error" }, "examples": { "code - version_precondition_failed": { "value": { "type": "base_error", "code": "version_precondition_failed", "message": "The version provided in the If-Match header did not match the current version of the resource", "ticket": "11t7n71hi5e6t" } } } } } }, "Resource_Management_APIs_415": { "description": "Unsupported Media Type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource_Management_APIs_api-error" }, "examples": { "code - unsupported_media_type": { "value": { "type": "base_error", "code": "unsupported_media_type", "message": "The Content-Type header was invalid", "ticket": "11t7n71hi5e6t" } } } } } }, "Resource_Management_APIs_500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource_Management_APIs_api-error" }, "examples": { "code - internal_server_failure ": { "value": { "type": "base_error", "code": "internal_server_failure", "message": "An unexpected error occurred while processing the request", "ticket": "11t7n71hi5e6t" } } } } } }, "Resource_Management_APIs_503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource_Management_APIs_api-error" }, "examples": { "code - service_unavailable": { "value": { "type": "base_error", "code": "service_unavailable", "message": "The service is currently unavailable", "ticket": "11t7n71hi5e6t" } } } } } }, "Resource_Management_APIs_400-with-message-body": { "description": "Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Resource_Management_APIs_api-error" }, { "$ref": "#/components/schemas/Resource_Management_APIs_constraint-violations-api-error" } ] }, "examples": { "code - invalid_request": { "value": { "type": "base_error", "code": "invalid_request", "message": "The request was invalid", "ticket": "11t7n71hi5e6t" } }, "code - request_constraint_violations": { "value": { "type": "constraint_violations_error", "code": "message_body_constraint_violations", "message": "The message body contained invalid fields", "ticket": "11t7n71hi5e6t", "violations": { "field1": { "code": "too_long", "constraintAttributes": { "maxLength": 10 } }, "field2": { "code": "not_null" } } } }, "code - message_body_constraint_violations": { "value": { "type": "constraint_violations_error", "code": "message_body_constraint_violations", "message": "The message body contained invalid fields", "ticket": "11t7n71hi5e6t", "violations": { "field1": { "code": "too_long", "constraintAttributes": { "maxLength": 10 } }, "field2": { "code": "not_null" } } } } } } } }, "Resource_Management_APIs_409-modification-conflict": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource_Management_APIs_api-error" }, "examples": { "code - modification_conflict": { "value": { "type": "base_error", "code": "modification_conflict", "message": "A modification conflict occurred when attempting to modify the resource", "ticket": "11t7n71hi5e6t" } } } } } }, "Resource_Management_APIs_404-user-not-found": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource_Management_APIs_api-error" }, "examples": { "code - user_not_found": { "value": { "type": "base_error", "code": "user_not_found", "message": "User could not be found", "ticket": "11t7n71hi5e6t" } } } } } } } }, "x-tagGroups": [ { "name": "Resource Management APIs", "tags": [ "Applications", "Auth Factors", "Auth Sessions", "Auth Session Policies", "Bot Detection Policies", "Custom Claims", "Custom Domains", "Email Brandings", "Email Domains", "Email Policies", "External IdP Profiles", "External IdP Tokens", "Identity Providers", "IdP Attribute Mappings", "IdP Role Mappings", "MFA Policies", "OAuth2 Clients", "Page Brandings", "Password Policies", "Permissions", "Permission Boundaries", "Permission Groups", "Refresh Tokens", "Remembered Tenants", "Roles", "Role Assignment Policies", "Signing Keys", "Tenants", "Users", "User Schemas", "Vanity Domains", "Webhook Policies", "Workflow Policies" ] } ] } ```