Create or adopt a user
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"
],
"userName": "<string>",
"externalId": "<string>",
"name": {
"formatted": "<string>",
"givenName": "<string>",
"familyName": "<string>"
},
"displayName": "<string>",
"emails": [
{
"value": "<string>",
"type": "<string>",
"primary": true
}
],
"active": true
}
'import requests
url = "https://{region}.api.plerion.com/v1/organization/scim/v2/Users"
payload = {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "<string>",
"externalId": "<string>",
"name": {
"formatted": "<string>",
"givenName": "<string>",
"familyName": "<string>"
},
"displayName": "<string>",
"emails": [
{
"value": "<string>",
"type": "<string>",
"primary": True
}
],
"active": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/scim+json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/scim+json'},
body: JSON.stringify({
schemas: ['urn:ietf:params:scim:schemas:core:2.0:User'],
userName: '<string>',
externalId: '<string>',
name: {formatted: '<string>', givenName: '<string>', familyName: '<string>'},
displayName: '<string>',
emails: [{value: '<string>', type: '<string>', primary: true}],
active: true
})
};
fetch('https://{region}.api.plerion.com/v1/organization/scim/v2/Users', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{region}.api.plerion.com/v1/organization/scim/v2/Users",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'schemas' => [
'urn:ietf:params:scim:schemas:core:2.0:User'
],
'userName' => '<string>',
'externalId' => '<string>',
'name' => [
'formatted' => '<string>',
'givenName' => '<string>',
'familyName' => '<string>'
],
'displayName' => '<string>',
'emails' => [
[
'value' => '<string>',
'type' => '<string>',
'primary' => true
]
],
'active' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/scim+json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{region}.api.plerion.com/v1/organization/scim/v2/Users"
payload := strings.NewReader("{\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:User\"\n ],\n \"userName\": \"<string>\",\n \"externalId\": \"<string>\",\n \"name\": {\n \"formatted\": \"<string>\",\n \"givenName\": \"<string>\",\n \"familyName\": \"<string>\"\n },\n \"displayName\": \"<string>\",\n \"emails\": [\n {\n \"value\": \"<string>\",\n \"type\": \"<string>\",\n \"primary\": true\n }\n ],\n \"active\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/scim+json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{region}.api.plerion.com/v1/organization/scim/v2/Users")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/scim+json")
.body("{\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:User\"\n ],\n \"userName\": \"<string>\",\n \"externalId\": \"<string>\",\n \"name\": {\n \"formatted\": \"<string>\",\n \"givenName\": \"<string>\",\n \"familyName\": \"<string>\"\n },\n \"displayName\": \"<string>\",\n \"emails\": [\n {\n \"value\": \"<string>\",\n \"type\": \"<string>\",\n \"primary\": true\n }\n ],\n \"active\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{region}.api.plerion.com/v1/organization/scim/v2/Users")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/scim+json'
request.body = "{\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:User\"\n ],\n \"userName\": \"<string>\",\n \"externalId\": \"<string>\",\n \"name\": {\n \"formatted\": \"<string>\",\n \"givenName\": \"<string>\",\n \"familyName\": \"<string>\"\n },\n \"displayName\": \"<string>\",\n \"emails\": [\n {\n \"value\": \"<string>\",\n \"type\": \"<string>\",\n \"primary\": true\n }\n ],\n \"active\": true\n}"
response = http.request(request)
puts response.read_body{
"schemas": [
"urn:ietf:params:scim:schemas:core: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>"
}
],
"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."
}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, switches the user to identity-provider sign-in, stops password sign-in for them, and clears the roles they held, so their user groups decide their roles from then on. 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 SCIM-managed user returns 409.
POST
/
v1
/
organization
/
scim
/
v2
/
Users
Create or adopt a user
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"
],
"userName": "<string>",
"externalId": "<string>",
"name": {
"formatted": "<string>",
"givenName": "<string>",
"familyName": "<string>"
},
"displayName": "<string>",
"emails": [
{
"value": "<string>",
"type": "<string>",
"primary": true
}
],
"active": true
}
'import requests
url = "https://{region}.api.plerion.com/v1/organization/scim/v2/Users"
payload = {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "<string>",
"externalId": "<string>",
"name": {
"formatted": "<string>",
"givenName": "<string>",
"familyName": "<string>"
},
"displayName": "<string>",
"emails": [
{
"value": "<string>",
"type": "<string>",
"primary": True
}
],
"active": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/scim+json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/scim+json'},
body: JSON.stringify({
schemas: ['urn:ietf:params:scim:schemas:core:2.0:User'],
userName: '<string>',
externalId: '<string>',
name: {formatted: '<string>', givenName: '<string>', familyName: '<string>'},
displayName: '<string>',
emails: [{value: '<string>', type: '<string>', primary: true}],
active: true
})
};
fetch('https://{region}.api.plerion.com/v1/organization/scim/v2/Users', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{region}.api.plerion.com/v1/organization/scim/v2/Users",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'schemas' => [
'urn:ietf:params:scim:schemas:core:2.0:User'
],
'userName' => '<string>',
'externalId' => '<string>',
'name' => [
'formatted' => '<string>',
'givenName' => '<string>',
'familyName' => '<string>'
],
'displayName' => '<string>',
'emails' => [
[
'value' => '<string>',
'type' => '<string>',
'primary' => true
]
],
'active' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/scim+json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{region}.api.plerion.com/v1/organization/scim/v2/Users"
payload := strings.NewReader("{\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:User\"\n ],\n \"userName\": \"<string>\",\n \"externalId\": \"<string>\",\n \"name\": {\n \"formatted\": \"<string>\",\n \"givenName\": \"<string>\",\n \"familyName\": \"<string>\"\n },\n \"displayName\": \"<string>\",\n \"emails\": [\n {\n \"value\": \"<string>\",\n \"type\": \"<string>\",\n \"primary\": true\n }\n ],\n \"active\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/scim+json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{region}.api.plerion.com/v1/organization/scim/v2/Users")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/scim+json")
.body("{\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:User\"\n ],\n \"userName\": \"<string>\",\n \"externalId\": \"<string>\",\n \"name\": {\n \"formatted\": \"<string>\",\n \"givenName\": \"<string>\",\n \"familyName\": \"<string>\"\n },\n \"displayName\": \"<string>\",\n \"emails\": [\n {\n \"value\": \"<string>\",\n \"type\": \"<string>\",\n \"primary\": true\n }\n ],\n \"active\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{region}.api.plerion.com/v1/organization/scim/v2/Users")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/scim+json'
request.body = "{\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:User\"\n ],\n \"userName\": \"<string>\",\n \"externalId\": \"<string>\",\n \"name\": {\n \"formatted\": \"<string>\",\n \"givenName\": \"<string>\",\n \"familyName\": \"<string>\"\n },\n \"displayName\": \"<string>\",\n \"emails\": [\n {\n \"value\": \"<string>\",\n \"type\": \"<string>\",\n \"primary\": true\n }\n ],\n \"active\": true\n}"
response = http.request(request)
puts response.read_body{
"schemas": [
"urn:ietf:params:scim:schemas:core: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>"
}
],
"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
application/scim+jsonapplication/json
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.
Example:
[
"urn:ietf:params:scim:schemas:core: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.
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.
Example:
[
"urn:ietf:params:scim:schemas:core: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
Show child attributes
Show child attributes
Was this page helpful?