> ## Documentation Index > Fetch the complete documentation index at: https://docs.plerion.com/llms.txt > Use this file to discover all available pages before exploring further. # Replace a user > Full replace of writable attributes; omitted writable attributes are cleared. id, groups, and meta are immutable. The first write to a Plerion user not yet under management adopts them, with the same effects as an adopting create. ## OpenAPI ````yaml /api-reference/scim-openapi.yaml put /v1/organization/scim/v2/Users/{userId} openapi: 3.1.0 info: title: Plerion SCIM 2.0 provisioning API version: v1 termsOfService: https://www.plerion.com/terms-and-conditions contact: name: Plerion Pty Ltd url: https://www.plerion.com/contact-us email: support@plerion.com license: name: Plerion Use License url: https://www.plerion.com/terms-and-conditions description: |- The Plerion SCIM 2.0 provisioning API lets an identity provider create, update, deactivate, and delete users in a Plerion organization, and keep its groups in sync as Plerion user groups. It follows RFC 7643 (schema) and RFC 7644 (protocol), so any SCIM 2.0 client can use it. SCIM carries users and groups, not roles. Roles are granted to user groups in the Plerion console, and every member holds them. Groups created through this API are owned by the identity provider: their name and membership cannot be edited in Plerion, and this API sees only the groups it created. Requests are authenticated with a Plerion organization API key sent as a bearer token. The organization is resolved from the key, so no request names an organization. Write operations need a key with the readWrite access level. The Plerion console shows the exact SCIM base URL for your organization in the SCIM provisioning section of your single sign-on settings. Paste that value into your identity provider rather than assembling it by hand. For setup instructions, see the SCIM provisioning guides. servers: - url: https://{region}.api.plerion.com description: Production API server - Select your preferred region variables: region: default: au enum: - au - sg1 - in1 - us1 security: - organizationApiKey: [] tags: - name: Discovery x-displayName: Discovery description: >- The SCIM discovery endpoints describe what this service supports. Identity providers read them automatically when you test a connection, and they advertise only the features that are actually available. - name: Users x-displayName: Users description: >- Create, read, update, deactivate, and delete users in a Plerion organization. Writes need an organization API key with the readWrite access level. - name: Groups x-displayName: Groups description: >- Create, read, update, and delete the user groups your identity provider manages, and their membership. Members must be users this API provisioned. Writes need an organization API key with the readWrite access level. paths: /v1/organization/scim/v2/Users/{userId}: parameters: - $ref: '#/components/parameters/userId' put: tags: - Users summary: Replace a user description: > Full replace of writable attributes; omitted writable attributes are cleared. id, groups, and meta are immutable. The first write to a Plerion user not yet under management adopts them, with the same effects as an adopting create. operationId: replaceUser requestBody: required: true content: application/scim+json: schema: $ref: '#/components/schemas/User' application/json: schema: $ref: '#/components/schemas/User' responses: '200': description: The updated user. content: application/scim+json: schema: $ref: '#/components/schemas/User' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/TooManyRequests' components: parameters: userId: name: userId in: path required: true description: The Plerion-assigned user id (SCIM id). schema: type: string format: uuid schemas: User: type: object description: > SCIM core User as supported by Plerion. Other standard SCIM attributes are accepted and returned unchanged but do not affect Plerion behavior. The user's Plerion sign-in email is derived from the payload with no configuration: userName when that value is an email address, otherwise the primary email, otherwise the work email. properties: schemas: type: array items: type: string example: - urn:ietf:params:scim:schemas:core:2.0:User id: type: string format: uuid readOnly: true description: Plerion-assigned identifier. Use it for all subsequent requests. externalId: type: string description: The identity provider's identifier for the user. Filterable. userName: type: string description: Required. Unique within the organization, case-insensitive. name: type: object properties: formatted: type: string givenName: type: string familyName: type: string displayName: type: string description: > The Plerion display name is taken from name.formatted, falling back to displayName, then "givenName familyName". emails: type: array items: $ref: '#/components/schemas/Email' active: type: boolean default: true description: > false deactivates the user. Sign-in is blocked, sessions end within seconds, and the user's API keys are revoked. The record is retained. groups: type: array readOnly: true items: $ref: '#/components/schemas/UserGroupRef' meta: $ref: '#/components/schemas/Meta' required: - schemas - userName Email: type: object properties: value: type: string description: The email address. type: type: string description: Label such as work or home. primary: type: boolean required: - value UserGroupRef: type: object readOnly: true description: > A user group the user belongs to, as pushed by the identity provider. Returned only when requested with ?attributes=groups. properties: $ref: 59875b84-4997-431d-b913-2e542a3e7605 value: type: string format: uuid description: Group id. display: type: string description: Group displayName. Meta: type: object readOnly: true properties: resourceType: type: string enum: - User - Group created: type: string format: date-time lastModified: type: string format: date-time version: type: string description: > Resource version identifier, for example W/"3". Conditional requests (If-Match, If-None-Match) are not supported. location: type: string format: uri Error: type: object description: RFC 7644 §3.12 error response. properties: schemas: type: array items: type: string const: urn:ietf:params:scim:api:messages:2.0:Error status: type: string description: HTTP status code as a string. example: '409' scimType: type: string enum: - invalidSyntax - invalidFilter - invalidPath - invalidValue - mutability - uniqueness detail: type: string example: A user with this userName already exists. required: - schemas - status responses: BadRequest: description: > Invalid request. The SCIM error body carries scimType invalidSyntax, invalidFilter, invalidPath, invalidValue, or mutability. content: application/scim+json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: > Missing or invalid API key. Rejected before the request reaches the SCIM service, so the body is plain JSON rather than a SCIM error. content: application/json: schema: type: object properties: message: type: string example: message: Unauthorized Forbidden: description: > Read-level key on a write operation, or an attempt to deactivate, delete, or change the role of a break-glass administrator. The detail then reads "A break-glass admin cannot be deactivated through SCIM" or "A break-glass admin cannot be deleted through SCIM", and the record is left untouched. Every other attribute of a break-glass administrator keeps syncing normally. content: application/scim+json: schema: $ref: '#/components/schemas/Error' NotFound: description: Resource not found. content: application/scim+json: schema: $ref: '#/components/schemas/Error' Conflict: description: | userName or email conflicts with an existing user (scimType uniqueness). content: application/scim+json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: Rate limited. Honor Retry-After and retry. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/scim+json: schema: $ref: '#/components/schemas/Error' headers: RetryAfter: description: Seconds to wait before retrying. schema: type: integer securitySchemes: organizationApiKey: type: http scheme: bearer description: > Plerion organization API key (plerion_oak_…), created by an organization admin in the Plerion console. Write operations require a key with readWrite access level; GET and .search work with read access level. ````