--- title: "Patch a User" method: PATCH path: "/scim/v2/Users/{user_id}" tags: ["SCIM"] --- # Patch a User `PATCH /scim/v2/Users/{user_id}` ## Request - Base URL: `https://api.byndid.com` - URL: `https://api.byndid.com/scim/v2/Users/{user_id}` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) To update only specific attributes of an existing user, send a PATCH request to `/Users/$USER_ID`. The PATCH operation is defined by [RFC-7644 §3.5.2](https://datatracker.ietf.org/doc/html/rfc7644#section-3.5.2). The request body MUST contain a valid SCIM PATCH request with a "schemas" value of "urn:ietf:params:scim:api:messages:2.0:PatchOp" and an "Operations" array with one or more PATCH operations. Values in the request body for immutable or read-only fields (as defined in [RFC-7643 §4.1](https://datatracker.ietf.org/doc/html/rfc7643#section-4.1)) will be ignored. Fields that are omitted from the request body will be left unchanged. Important implementation notes: - The Beyond Identity SCIM server currently does not support atomic PATCH operations - The server supports two types of PATCH operations: 1. Email Update: Must use "add" operation with path "emails" and value containing the email object (see "Update Email" example) 2. Generic Update: A path which isn't equal to "emails" is ignored and the value must be a JSON object representing the user resource - If a request contains multiple operations, the request may be partially applied: 1. The server first validates the overall request schema and attribute types 2. Operations are then applied sequentially in the order provided 3. If any operation fails, processing stops immediately 4. Previously successful operations remain applied 5. The error response does not indicate which operation failed or which operations were applied 6. To determine the current state, clients should issue a GET request after receiving an error Important notes about email handling: - Only one email address is supported per user - The email must be marked as primary (primary: true) - If multiple email addresses are provided, only the primary email will be used and all others will be ignored ## Path parameters - `user_id` string, required ## Request body - object: Request for UpdateUser. Due to the complexity of SCIM PATCH operations, it is strongly recommended to refer to the examples for proper request formatting and supported operations. - `schemas` string[], required - `Operations` object[], required - `op` 'add' | 'replace', required: The operation to be performed. The operation follows the SCIM specification for PATCH operations. Please refer to the [SCIM specification](https://datatracker.ietf.org/doc/html/rfc7644#section-3.5.2) for more information. For the Beyond Identity SCIM server, the supported operations are as follows: - add - replace - `path` string: The path to the attribute to be updated. The path follows the SCIM specification for PATCH operations. Please refer to the [SCIM specification](https://datatracker.ietf.org/doc/html/rfc7644#section-3.5.2) for more information. For the Beyond Identity SCIM server, the supported paths are as follows: - emails - name - displayName - urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber - `value` object, required: The value to be updated. The structure of the value is dependent on the path. Please refer to the examples for proper request formatting. For example, the value for the path "emails" must be an array of email objects as follows: ```json [ { "value": "new.email@example.com", "primary": true, "type": "work" } ] ``` The value for the path "name" must be an object with the following properties: ```json { "familyName": "Smith", "givenName": "Barbara" } ``` The value for the path "displayName" must be a string representing the display name of the user. ## Response `200` Successfully updated the User resource. The response contains the full representation of the modified User, including any server-side changes and read-only attributes as specified in [RFC-7644 §3.5.2](https://datatracker.ietf.org/doc/html/rfc7644#section-3.5.2). - SCIMUser: A user represents a human entity as defined by [RFC 7643 Section 4.1](https://www.rfc-editor.org/rfc/rfc7643#section-4.1). The externalId attribute must be unique across all users in the system. - `schemas` string[], required: The list of schemas used to define the user. This must contain only the core User schema ("urn:ietf:params:scim:schemas:core:2.0:User"). - `id` string: The unique ID of the user. This is automatically generated on creation. This field is immutable and output-only. - `externalId` string: The provisioning client's unique identifier for the resource. This value must be unique across all users. - `userName` string: The unique username of the user. The value of this field will be returned as the subject of an OIDC ID Token. - `displayName` string: Display name of the User. This name is used for display purposes. - `active` boolean: Indicator for the user's administrative status. If true, the user has administrative capabilities. - `emails` object[]: The list containing the user's emails. Important notes about email handling: - Only one email address is supported per user - The email must be marked as primary (primary: true) - If multiple email addresses are provided, only the primary email will be used and all others will be ignored - `primary` boolean: Indicator for the primary email address. Important notes about email handling: - Only one email address is supported per user - The email must be marked as primary (primary: true) - If multiple email addresses are provided, only the primary email will be used and all others will be ignored - `value` string: The email address. Important notes about email handling: - Only one email address is supported per user - The email must be marked as primary (primary: true) - If multiple email addresses are provided, only the primary email will be used and all others will be ignored - `type` 'work' | 'home' | 'other': The type of email address. Valid values are "work", "home", and "other" as defined in [RFC 7643](https://www.rfc-editor.org/rfc/rfc7643). Important notes about email handling: - Only one email address is supported per user - The email must be marked as primary (primary: true) - If multiple email addresses are provided, only the primary email will be used and all others will be ignored - `name` object: Definition of the user's name. - `givenName` string: The given name of the user, or first name in most Western languages. - `familyName` string: The family name of the user, or last name in most Western languages. - `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User` object: The Employee Number as defined in the enterprise SCIM extension - `employeeNumber` string: A string identifier, typically numeric or alphanumeric, assigned to a person, typically based on order of hire or association with an organization as defined in [RFC 7643](https://datatracker.ietf.org/doc/html/rfc7643#section-4.3). - `groups` object[]: A list of groups that the user belongs to, as defined in [RFC 7643 Section 4.1.2](https://www.rfc-editor.org/rfc/rfc7643#section-4.1.2). This is a read-only attribute populated by the service provider. - `value` string: The identifier of the group. - `$ref` string: The URI of the corresponding group resource. - `type` string: A label indicating the attribute's function, e.g., 'direct' for direct group membership. Beyond Identity SCIM server supports only 'direct' membership for groups. Indirect membership is not supported. - `meta` object: Resource metadata as defined in [RFC 7643 Section 3.1](https://www.rfc-editor.org/rfc/rfc7643#section-3.1). This attribute is only populated on responses and is ignored on requests. - `resourceType` string, required: The name of the resource type of the resource. - `created` string, date-time, required: Timestamp of when the resource was created. - `lastModified` string, date-time, required: Timestamp of when the resource was last updated. - `location` string, required: The URI of the resource being returned. - `version` string, required: The version of the resource being returned. This is always "W/0". ## Other responses - `400`: Request validation error. May occur due to: - Invalid PATCH operation syntax - Attempt to modify read-only attributes - Invalid attribute values - Schema validation failures - Missing or invalid email configuration - Unsupported operation types - `401`: Unauthorized. - `404`: The resource was not found. - `429`: Rate limit exceeded. - `500`: Server error. --- [API](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-workforce-api.md) - [All operations](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-workforce-api/llms.txt) - [OpenAPI document](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-workforce-api/revisions/562e14b2e4ba?raw)