Update a user
curl --request PATCH \
--url https://api.identity.v2.portao3.com.br/realms/{realmId}/users/{userId} \
--header 'Content-Type: application/json' \
--data '
{
"firstName": "Ana",
"lastName": "Souza",
"cpf": "52998224725",
"birthdate": "1990-05-17T00:00:00.000Z",
"phone": "+5511987654321",
"realm": {
"level": "USER"
},
"organizations": [
{
"id": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"level": "USER"
}
],
"customFields": {}
}
'import requests
url = "https://api.identity.v2.portao3.com.br/realms/{realmId}/users/{userId}"
payload = {
"firstName": "Ana",
"lastName": "Souza",
"cpf": "52998224725",
"birthdate": "1990-05-17T00:00:00.000Z",
"phone": "+5511987654321",
"realm": { "level": "USER" },
"organizations": [
{
"id": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"level": "USER"
}
],
"customFields": {}
}
headers = {"Content-Type": "application/json"}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
firstName: 'Ana',
lastName: 'Souza',
cpf: '52998224725',
birthdate: '1990-05-17T00:00:00.000Z',
phone: '+5511987654321',
realm: {level: 'USER'},
organizations: [{id: 'c4bd3f21-dfbd-44e8-8055-68ba15bed410', level: 'USER'}],
customFields: {}
})
};
fetch('https://api.identity.v2.portao3.com.br/realms/{realmId}/users/{userId}', 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://api.identity.v2.portao3.com.br/realms/{realmId}/users/{userId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'firstName' => 'Ana',
'lastName' => 'Souza',
'cpf' => '52998224725',
'birthdate' => '1990-05-17T00:00:00.000Z',
'phone' => '+5511987654321',
'realm' => [
'level' => 'USER'
],
'organizations' => [
[
'id' => 'c4bd3f21-dfbd-44e8-8055-68ba15bed410',
'level' => 'USER'
]
],
'customFields' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/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://api.identity.v2.portao3.com.br/realms/{realmId}/users/{userId}"
payload := strings.NewReader("{\n \"firstName\": \"Ana\",\n \"lastName\": \"Souza\",\n \"cpf\": \"52998224725\",\n \"birthdate\": \"1990-05-17T00:00:00.000Z\",\n \"phone\": \"+5511987654321\",\n \"realm\": {\n \"level\": \"USER\"\n },\n \"organizations\": [\n {\n \"id\": \"c4bd3f21-dfbd-44e8-8055-68ba15bed410\",\n \"level\": \"USER\"\n }\n ],\n \"customFields\": {}\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.identity.v2.portao3.com.br/realms/{realmId}/users/{userId}")
.header("Content-Type", "application/json")
.body("{\n \"firstName\": \"Ana\",\n \"lastName\": \"Souza\",\n \"cpf\": \"52998224725\",\n \"birthdate\": \"1990-05-17T00:00:00.000Z\",\n \"phone\": \"+5511987654321\",\n \"realm\": {\n \"level\": \"USER\"\n },\n \"organizations\": [\n {\n \"id\": \"c4bd3f21-dfbd-44e8-8055-68ba15bed410\",\n \"level\": \"USER\"\n }\n ],\n \"customFields\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.identity.v2.portao3.com.br/realms/{realmId}/users/{userId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"firstName\": \"Ana\",\n \"lastName\": \"Souza\",\n \"cpf\": \"52998224725\",\n \"birthdate\": \"1990-05-17T00:00:00.000Z\",\n \"phone\": \"+5511987654321\",\n \"realm\": {\n \"level\": \"USER\"\n },\n \"organizations\": [\n {\n \"id\": \"c4bd3f21-dfbd-44e8-8055-68ba15bed410\",\n \"level\": \"USER\"\n }\n ],\n \"customFields\": {}\n}"
response = http.request(request)
puts response.read_body{
"id": "8f1c2d3e-4b5a-4c6d-9e7f-a1b2c3d4e5f6",
"email": "ana.souza@acme.com.br",
"firstName": "Ana",
"lastName": "Souza",
"cpf": "52998224725",
"status": "ACTIVE",
"statusCode": "USER_ACTIVE",
"realm": {
"id": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
"level": "USER",
"name": ""
},
"hasMfa": true,
"hasPin": true,
"hasFacialBiometric": true,
"pinErrorsCount": 0,
"mfaErrorsCount": 0,
"createdAt": "2026-03-02T14:21:07.512Z",
"updatedAt": "2026-10-13T18:43:50.746Z",
"createdBy": "43230779-2cfb-4525-a40c-77fbf15e68f0",
"updatedBy": "43230779-2cfb-4525-a40c-77fbf15e68f0",
"deletedBy": "",
"organizations": [
{
"id": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"level": "USER",
"legalName": "Acme Comércio de Alimentos Ltda",
"tradingName": "Acme Alimentos"
}
],
"birthdate": "1990-05-17T00:00:00.000Z",
"phone": "+5511987654321",
"customFields": {}
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "FORBIDDEN_USER",
"origin": "IDENTITY",
"message": "You do not have permission to perform this action on this user"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "USER_NOT_FOUND",
"origin": "IDENTITY",
"message": "User not found"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "BAD_REQUEST",
"origin": "IDENTITY",
"message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.",
"fields": [
{
"field": "userId",
"message": "Invalid UUID",
"code": "USERID_UUID"
}
]
}Update a user
Updates a user’s profile, and adds them to organizations or changes their level in the organizations they belong to.
PATCH
/
realms
/
{realmId}
/
users
/
{userId}
Update a user
curl --request PATCH \
--url https://api.identity.v2.portao3.com.br/realms/{realmId}/users/{userId} \
--header 'Content-Type: application/json' \
--data '
{
"firstName": "Ana",
"lastName": "Souza",
"cpf": "52998224725",
"birthdate": "1990-05-17T00:00:00.000Z",
"phone": "+5511987654321",
"realm": {
"level": "USER"
},
"organizations": [
{
"id": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"level": "USER"
}
],
"customFields": {}
}
'import requests
url = "https://api.identity.v2.portao3.com.br/realms/{realmId}/users/{userId}"
payload = {
"firstName": "Ana",
"lastName": "Souza",
"cpf": "52998224725",
"birthdate": "1990-05-17T00:00:00.000Z",
"phone": "+5511987654321",
"realm": { "level": "USER" },
"organizations": [
{
"id": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"level": "USER"
}
],
"customFields": {}
}
headers = {"Content-Type": "application/json"}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
firstName: 'Ana',
lastName: 'Souza',
cpf: '52998224725',
birthdate: '1990-05-17T00:00:00.000Z',
phone: '+5511987654321',
realm: {level: 'USER'},
organizations: [{id: 'c4bd3f21-dfbd-44e8-8055-68ba15bed410', level: 'USER'}],
customFields: {}
})
};
fetch('https://api.identity.v2.portao3.com.br/realms/{realmId}/users/{userId}', 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://api.identity.v2.portao3.com.br/realms/{realmId}/users/{userId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'firstName' => 'Ana',
'lastName' => 'Souza',
'cpf' => '52998224725',
'birthdate' => '1990-05-17T00:00:00.000Z',
'phone' => '+5511987654321',
'realm' => [
'level' => 'USER'
],
'organizations' => [
[
'id' => 'c4bd3f21-dfbd-44e8-8055-68ba15bed410',
'level' => 'USER'
]
],
'customFields' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/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://api.identity.v2.portao3.com.br/realms/{realmId}/users/{userId}"
payload := strings.NewReader("{\n \"firstName\": \"Ana\",\n \"lastName\": \"Souza\",\n \"cpf\": \"52998224725\",\n \"birthdate\": \"1990-05-17T00:00:00.000Z\",\n \"phone\": \"+5511987654321\",\n \"realm\": {\n \"level\": \"USER\"\n },\n \"organizations\": [\n {\n \"id\": \"c4bd3f21-dfbd-44e8-8055-68ba15bed410\",\n \"level\": \"USER\"\n }\n ],\n \"customFields\": {}\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.identity.v2.portao3.com.br/realms/{realmId}/users/{userId}")
.header("Content-Type", "application/json")
.body("{\n \"firstName\": \"Ana\",\n \"lastName\": \"Souza\",\n \"cpf\": \"52998224725\",\n \"birthdate\": \"1990-05-17T00:00:00.000Z\",\n \"phone\": \"+5511987654321\",\n \"realm\": {\n \"level\": \"USER\"\n },\n \"organizations\": [\n {\n \"id\": \"c4bd3f21-dfbd-44e8-8055-68ba15bed410\",\n \"level\": \"USER\"\n }\n ],\n \"customFields\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.identity.v2.portao3.com.br/realms/{realmId}/users/{userId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"firstName\": \"Ana\",\n \"lastName\": \"Souza\",\n \"cpf\": \"52998224725\",\n \"birthdate\": \"1990-05-17T00:00:00.000Z\",\n \"phone\": \"+5511987654321\",\n \"realm\": {\n \"level\": \"USER\"\n },\n \"organizations\": [\n {\n \"id\": \"c4bd3f21-dfbd-44e8-8055-68ba15bed410\",\n \"level\": \"USER\"\n }\n ],\n \"customFields\": {}\n}"
response = http.request(request)
puts response.read_body{
"id": "8f1c2d3e-4b5a-4c6d-9e7f-a1b2c3d4e5f6",
"email": "ana.souza@acme.com.br",
"firstName": "Ana",
"lastName": "Souza",
"cpf": "52998224725",
"status": "ACTIVE",
"statusCode": "USER_ACTIVE",
"realm": {
"id": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
"level": "USER",
"name": ""
},
"hasMfa": true,
"hasPin": true,
"hasFacialBiometric": true,
"pinErrorsCount": 0,
"mfaErrorsCount": 0,
"createdAt": "2026-03-02T14:21:07.512Z",
"updatedAt": "2026-10-13T18:43:50.746Z",
"createdBy": "43230779-2cfb-4525-a40c-77fbf15e68f0",
"updatedBy": "43230779-2cfb-4525-a40c-77fbf15e68f0",
"deletedBy": "",
"organizations": [
{
"id": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"level": "USER",
"legalName": "Acme Comércio de Alimentos Ltda",
"tradingName": "Acme Alimentos"
}
],
"birthdate": "1990-05-17T00:00:00.000Z",
"phone": "+5511987654321",
"customFields": {}
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "FORBIDDEN_USER",
"origin": "IDENTITY",
"message": "You do not have permission to perform this action on this user"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "USER_NOT_FOUND",
"origin": "IDENTITY",
"message": "User not found"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "BAD_REQUEST",
"origin": "IDENTITY",
"message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.",
"fields": [
{
"field": "userId",
"message": "Invalid UUID",
"code": "USERID_UUID"
}
]
}Send only the fields to change: an omitted field, or an empty
firstName, lastName or cpf, keeps the current value. Listing an organization the user doesn’t belong to yet adds them to it with a personal wallet, like POST /realms/{realmId}/users/{userId}/organizations/{organizationId}/assign; organizations you don’t list are kept. The e-mail address can’t be changed. Only a realm administrator can update another user: an API client, which is an organization admin, gets 403.Path Parameters
ID of your realm.
Format: UUID
ID of the user to update.
Format: UUID
Body
application/json
First name. An empty value keeps the current one.
Example:
"Ana"
Last name. An empty value keeps the current one.
Example:
"Souza"
CPF, digits only. Must be a valid CPF; an empty value keeps the current one.
Example:
"52998224725"
Date of birth, as an ISO 8601 date-time at midnight UTC. A plain YYYY-MM-DD date is also accepted.
Example:
"1990-05-17T00:00:00.000Z"
Phone number in E.164 format: +, the country code and the number, digits only. Mobile or landline, Brazilian or not.
Pattern:
^\+[1-9]\d{7,14}$Example:
"+5511987654321"
The user's realm.
Show child attributes
Show child attributes
Organizations to update or add. A listed organization the user already belongs to gets the new level; one they don't belong to yet is added, with a personal wallet. Organizations you don't list are kept.
Show child attributes
Show child attributes
Values of the realm's user custom fields, keyed by the custom field's slug, for example {"cost-center": "Marketing"}. Replaces every stored value: send {} to clear them, or omit the field to keep them.
Show child attributes
Show child attributes
Response
Successful response
A user of the realm.
ID of the user.
Example:
"8f1c2d3e-4b5a-4c6d-9e7f-a1b2c3d4e5f6"
E-mail address the user signs in with. It can't be changed.
Example:
"ana.souza@acme.com.br"
First name.
Example:
"Ana"
Last name.
Example:
"Souza"
CPF, digits only.
Example:
"52998224725"
Lifecycle status. IN_ONBOARDING: invited, still completing onboarding. ACTIVE: can sign in. DEACTIVATED: access removed by an administrator. BLOCKED: access suspended, for example after too many wrong PINs. CREATING: being set up.
Available options:
IN_ONBOARDING, CREATING, ACTIVE, DEACTIVATED, BLOCKED Example:
"ACTIVE"
Reason behind status: USER_ACTIVE, USER_DEACTIVATED, ONLY_ONBOARDING, or the cause of a block (BLOCKED_BY_PIN, BLOCKED_BY_MFA, BLOCKED_BY_ADMIN).
Available options:
BLOCKED_BY_PIN, BLOCKED_BY_MFA, BLOCKED_BY_ADMIN, USER_ACTIVE, USER_DEACTIVATED, ONLY_ONBOARDING Example:
"USER_ACTIVE"
The user's realm and their access level in it.
Show child attributes
Show child attributes
Whether the user has set up multi-factor authentication.
Example:
true
Whether the user has created a transaction PIN.
Example:
true
Whether the user's face was validated during onboarding.
Example:
true
Consecutive wrong PIN attempts. At 3 the user is blocked (BLOCKED_BY_PIN).
Example:
0
Consecutive wrong multi-factor codes.
Example:
0
When the user was created.
Example:
"2026-03-02T14:21:07.512Z"
When the user last changed.
Example:
"2026-10-13T18:43:50.746Z"
ID of the user or API client that created this user. Empty when unknown.
Example:
"43230779-2cfb-4525-a40c-77fbf15e68f0"
ID of the user or API client that last changed this user. Empty when unknown.
Example:
"43230779-2cfb-4525-a40c-77fbf15e68f0"
ID of the user or API client that deactivated this user. Empty unless the user was deactivated.
Example:
""
Organizations of the realm the user belongs to.
Show child attributes
Show child attributes
Date of birth, at midnight UTC.
Example:
"1990-05-17T00:00:00.000Z"
Phone number in E.164 format. Omitted when the user has none.
Example:
"+5511987654321"
Values of the realm's user custom fields, keyed by the custom field's slug, for example {"cost-center": "Marketing"}. Omitted when the user has none.
Show child attributes
Show child attributes