curl --request POST \
--url https://{region}.api.plerion.com/v1/organization/scim/v2/Users \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/scim+json' \
--data '
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"externalId": "8b1fbb4e-2c1d-4f3a-9d5e-7a6b5c4d3e2f",
"userName": "jdoe@example.com",
"name": {
"givenName": "Jane",
"familyName": "Doe",
"formatted": "Jane Doe"
},
"emails": [
{
"value": "jane.doe@example.com",
"type": "work",
"primary": true
}
],
"active": true
}
'{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:plerion:scim:schemas:extension:2.0:User"
],
"userName": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"externalId": "<string>",
"name": {
"formatted": "<string>",
"givenName": "<string>",
"familyName": "<string>"
},
"displayName": "<string>",
"emails": [
{
"value": "<string>",
"type": "<string>",
"primary": true
}
],
"active": true,
"groups": [
{
"type": "<unknown>",
"format": "<unknown>",
"value": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"display": "<string>"
}
],
"urn:plerion:scim:schemas:extension:2.0:User": {
"ssoUser": true
},
"meta": {
"resourceType": "User",
"created": "2023-11-07T05:31:56Z",
"lastModified": "2023-11-07T05:31:56Z",
"version": "<string>",
"location": "<string>"
}
}{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:Error"
],
"status": "409",
"scimType": "invalidSyntax",
"detail": "A user with this userName already exists."
}{
"message": "Unauthorized"
}{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:Error"
],
"status": "409",
"scimType": "invalidSyntax",
"detail": "A user with this userName already exists."
}{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:Error"
],
"status": "409",
"scimType": "invalidSyntax",
"detail": "A user with this userName already exists."
}{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:Error"
],
"status": "409",
"scimType": "invalidSyntax",
"detail": "A user with this userName already exists."
}Create or adopt a user
Creates a user, or adopts an existing Plerion user whose sign-in email (derived from the payload, case-insensitive) matches. Adoption returns 201 with the existing user’s id and sets the SCIM managed marker. It changes nothing else: the roles the user holds stay as they are, and the way they sign in is unchanged. A break-glass administrator can be adopted like anyone else and keeps both password sign-in and their roles. A userName already used by another user returns 409.
Send the Plerion extension with ssoUser set to false to create a user who signs in with a password instead of through single sign-on. It defaults to true. No invitation email is sent either way; a password user sets their password through the forgot password flow.
curl --request POST \
--url https://{region}.api.plerion.com/v1/organization/scim/v2/Users \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/scim+json' \
--data '
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"externalId": "8b1fbb4e-2c1d-4f3a-9d5e-7a6b5c4d3e2f",
"userName": "jdoe@example.com",
"name": {
"givenName": "Jane",
"familyName": "Doe",
"formatted": "Jane Doe"
},
"emails": [
{
"value": "jane.doe@example.com",
"type": "work",
"primary": true
}
],
"active": true
}
'{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:plerion:scim:schemas:extension:2.0:User"
],
"userName": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"externalId": "<string>",
"name": {
"formatted": "<string>",
"givenName": "<string>",
"familyName": "<string>"
},
"displayName": "<string>",
"emails": [
{
"value": "<string>",
"type": "<string>",
"primary": true
}
],
"active": true,
"groups": [
{
"type": "<unknown>",
"format": "<unknown>",
"value": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"display": "<string>"
}
],
"urn:plerion:scim:schemas:extension:2.0:User": {
"ssoUser": true
},
"meta": {
"resourceType": "User",
"created": "2023-11-07T05:31:56Z",
"lastModified": "2023-11-07T05:31:56Z",
"version": "<string>",
"location": "<string>"
}
}{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:Error"
],
"status": "409",
"scimType": "invalidSyntax",
"detail": "A user with this userName already exists."
}{
"message": "Unauthorized"
}{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:Error"
],
"status": "409",
"scimType": "invalidSyntax",
"detail": "A user with this userName already exists."
}{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:Error"
],
"status": "409",
"scimType": "invalidSyntax",
"detail": "A user with this userName already exists."
}{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:Error"
],
"status": "409",
"scimType": "invalidSyntax",
"detail": "A user with this userName already exists."
}Authorizations
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.
Body
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.
A user maintained outside Plerion, by an identity provider sync or by calls to this API, is badged SCIM managed in the Plerion console. The badge does not stop this API from changing the user, but the next sync may overwrite the change.
[
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:plerion:scim:schemas:extension:2.0:User"
]
Required. Unique within the organization, case-insensitive.
The identity provider's identifier for the user. Filterable.
Show child attributes
Show child attributes
The Plerion display name is taken from name.formatted, falling back to displayName, then "givenName familyName".
Show child attributes
Show child attributes
false deactivates the user. Sign-in is blocked, sessions end within seconds, and the user's API keys are revoked. The record is retained.
Plerion schema extension for the User resource, urn:plerion:scim:schemas:extension:2.0:User. It carries the one attribute SCIM has no place for: how the user signs in.
Show child attributes
Show child attributes
Response
User created or adopted.
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.
A user maintained outside Plerion, by an identity provider sync or by calls to this API, is badged SCIM managed in the Plerion console. The badge does not stop this API from changing the user, but the next sync may overwrite the change.
[
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:plerion:scim:schemas:extension:2.0:User"
]
Required. Unique within the organization, case-insensitive.
Plerion-assigned identifier. Use it for all subsequent requests.
The identity provider's identifier for the user. Filterable.
Show child attributes
Show child attributes
The Plerion display name is taken from name.formatted, falling back to displayName, then "givenName familyName".
Show child attributes
Show child attributes
false deactivates the user. Sign-in is blocked, sessions end within seconds, and the user's API keys are revoked. The record is retained.
Show child attributes
Show child attributes
Plerion schema extension for the User resource, urn:plerion:scim:schemas:extension:2.0:User. It carries the one attribute SCIM has no place for: how the user signs in.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Was this page helpful?