POST /v1/users

from metadata.sdk import configure
from metadata.sdk.entities import Users
from metadata.generated.schema.api.teams.createUser import CreateUserRequest

configure(
    host="https://your-company.open-metadata.org/api",
    jwt_token="your-jwt-token"
)

request = CreateUserRequest(
    name="aaron_johnson0",
    displayName="Aaron Johnson",
    email="aaron_johnson0@gmail.com",
    description="Data analyst in the Sales team",
    teams=["Sales"],
    roles=["DataSteward"]
)

user = Users.create(request)
print(f"Created: {user.fullyQualifiedName.root}")

import org.openmetadata.schema.api.teams.CreateUser;

// client is an initialized OpenMetadataClient.
var request = new CreateUser()
    .withName("aaron_johnson0")
    .withDisplayName("Aaron Johnson")
    .withEmail("aaron_johnson0@gmail.com")
    .withDescription("Data analyst in the Sales team");

var user = client.users().create(request);

curl -X POST "{base_url}/api/v1/users" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "aaron_johnson0",
    "displayName": "Aaron Johnson",
    "email": "aaron_johnson0@gmail.com",
    "description": "Data analyst in the Sales team",
    "teams": ["Sales"],
    "roles": ["DataSteward"]
  }'

{
  "id": "77655e6e-ad33-49da-bbca-db4ba4d4e2cd",
  "name": "aaron_johnson0",
  "fullyQualifiedName": "aaron_johnson0",
  "displayName": "Aaron Johnson",
  "version": 0.1,
  "updatedAt": 1769982624214,
  "updatedBy": "admin",
  "email": "aaron_johnson0@gmail.com",
  "href": "http://localhost:8585/api/v1/users/77655e6e-ad33-49da-bbca-db4ba4d4e2cd",
  "isBot": false,
  "isAdmin": false,
  "allowImpersonation": false,
  "teams": [
    {
      "id": "7a2b921b-f623-4eb5-9736-649788ad842c",
      "type": "team",
      "name": "Sales",
      "fullyQualifiedName": "Sales",
      "displayName": "Sales",
      "deleted": false
    }
  ],
  "personas": [],
  "deleted": false,
  "roles": [
    {
      "id": "761c2bb2-0b77-4bc5-9af9-cf89536d6a12",
      "type": "role",
      "name": "DataSteward",
      "fullyQualifiedName": "DataSteward",
      "displayName": "Data Steward",
      "deleted": false
    }
  ],
  "domains": []
}

POST

users

POST /v1/users

from metadata.sdk import configure
from metadata.sdk.entities import Users
from metadata.generated.schema.api.teams.createUser import CreateUserRequest

configure(
    host="https://your-company.open-metadata.org/api",
    jwt_token="your-jwt-token"
)

request = CreateUserRequest(
    name="aaron_johnson0",
    displayName="Aaron Johnson",
    email="aaron_johnson0@gmail.com",
    description="Data analyst in the Sales team",
    teams=["Sales"],
    roles=["DataSteward"]
)

user = Users.create(request)
print(f"Created: {user.fullyQualifiedName.root}")

import org.openmetadata.schema.api.teams.CreateUser;

// client is an initialized OpenMetadataClient.
var request = new CreateUser()
    .withName("aaron_johnson0")
    .withDisplayName("Aaron Johnson")
    .withEmail("aaron_johnson0@gmail.com")
    .withDescription("Data analyst in the Sales team");

var user = client.users().create(request);

curl -X POST "{base_url}/api/v1/users" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "aaron_johnson0",
    "displayName": "Aaron Johnson",
    "email": "aaron_johnson0@gmail.com",
    "description": "Data analyst in the Sales team",
    "teams": ["Sales"],
    "roles": ["DataSteward"]
  }'

{
  "id": "77655e6e-ad33-49da-bbca-db4ba4d4e2cd",
  "name": "aaron_johnson0",
  "fullyQualifiedName": "aaron_johnson0",
  "displayName": "Aaron Johnson",
  "version": 0.1,
  "updatedAt": 1769982624214,
  "updatedBy": "admin",
  "email": "aaron_johnson0@gmail.com",
  "href": "http://localhost:8585/api/v1/users/77655e6e-ad33-49da-bbca-db4ba4d4e2cd",
  "isBot": false,
  "isAdmin": false,
  "allowImpersonation": false,
  "teams": [
    {
      "id": "7a2b921b-f623-4eb5-9736-649788ad842c",
      "type": "team",
      "name": "Sales",
      "fullyQualifiedName": "Sales",
      "displayName": "Sales",
      "deleted": false
    }
  ],
  "personas": [],
  "deleted": false,
  "roles": [
    {
      "id": "761c2bb2-0b77-4bc5-9af9-cf89536d6a12",
      "type": "role",
      "name": "DataSteward",
      "fullyQualifiedName": "DataSteward",
      "displayName": "Data Steward",
      "deleted": false
    }
  ],
  "domains": []
}

Create a User

Create a new user in your organization.

Permissions

Starting in OpenMetadata 2.0.3, assigning a user to a closed team (isJoinable: false) during creation requires an administrator.

Body Parameters

string

required

Username for the user. Must be unique across the organization.

string

required

Email address of the user. Must be unique across the organization.

string

Human-readable display name for the user.

string

Description of the user in Markdown format.

boolean

default:"false"

Whether this user is a bot account.

boolean

default:"false"

Whether this user has admin privileges.

array

Array of team fully qualified names to assign the user to.

array

Array of role fully qualified names to assign to the user.

array

Array of persona references to assign to the user.

array

Fully qualified names of the domains to assign for governance purposes.

object

Profile information for the user.

Show properties

object

Profile images for the user.

string

Timezone of the user, for example America/New_York.

POST /v1/users

from metadata.sdk import configure
from metadata.sdk.entities import Users
from metadata.generated.schema.api.teams.createUser import CreateUserRequest

configure(
    host="https://your-company.open-metadata.org/api",
    jwt_token="your-jwt-token"
)

request = CreateUserRequest(
    name="aaron_johnson0",
    displayName="Aaron Johnson",
    email="aaron_johnson0@gmail.com",
    description="Data analyst in the Sales team",
    teams=["Sales"],
    roles=["DataSteward"]
)

user = Users.create(request)
print(f"Created: {user.fullyQualifiedName.root}")

import org.openmetadata.schema.api.teams.CreateUser;

// client is an initialized OpenMetadataClient.
var request = new CreateUser()
    .withName("aaron_johnson0")
    .withDisplayName("Aaron Johnson")
    .withEmail("aaron_johnson0@gmail.com")
    .withDescription("Data analyst in the Sales team");

var user = client.users().create(request);

curl -X POST "{base_url}/api/v1/users" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "aaron_johnson0",
    "displayName": "Aaron Johnson",
    "email": "aaron_johnson0@gmail.com",
    "description": "Data analyst in the Sales team",
    "teams": ["Sales"],
    "roles": ["DataSteward"]
  }'

{
  "id": "77655e6e-ad33-49da-bbca-db4ba4d4e2cd",
  "name": "aaron_johnson0",
  "fullyQualifiedName": "aaron_johnson0",
  "displayName": "Aaron Johnson",
  "version": 0.1,
  "updatedAt": 1769982624214,
  "updatedBy": "admin",
  "email": "aaron_johnson0@gmail.com",
  "href": "http://localhost:8585/api/v1/users/77655e6e-ad33-49da-bbca-db4ba4d4e2cd",
  "isBot": false,
  "isAdmin": false,
  "allowImpersonation": false,
  "teams": [
    {
      "id": "7a2b921b-f623-4eb5-9736-649788ad842c",
      "type": "team",
      "name": "Sales",
      "fullyQualifiedName": "Sales",
      "displayName": "Sales",
      "deleted": false
    }
  ],
  "personas": [],
  "deleted": false,
  "roles": [
    {
      "id": "761c2bb2-0b77-4bc5-9af9-cf89536d6a12",
      "type": "role",
      "name": "DataSteward",
      "fullyQualifiedName": "DataSteward",
      "displayName": "Data Steward",
      "deleted": false
    }
  ],
  "domains": []
}

Returns

Returns the created user object with all specified properties and system-generated fields.

Response

string

Unique identifier for the user (UUID format).

string

Username.

string

Fully qualified name (same as name for users).

string

Human-readable display name.

string

Email address of the user.

boolean

Whether this user is a bot account.

boolean

Whether this user has admin privileges.

array

Teams the user belongs to.

Show properties

string

UUID of the team.

string

Type of entity (always team).

string

Name of the team.

string

Fully qualified name of the team.

array

Roles assigned to the user.

Show properties

string

UUID of the role.

string

Type of entity (always role).

string

Name of the role.

string

Fully qualified name of the role.

array

Personas assigned to the user.

array

Domain assignments for governance.

number

Version number for the entity (starts at 0.1).

Create or Update (PUT)

Use PUT /v1/users instead of POST to perform an upsert. If a user with the same fullyQualifiedName already exists, it will be updated; otherwise, a new user is created. The request body is the same as POST.

curl -X PUT "{base_url}/api/v1/users" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ ... same body as POST ... }'

PUT will not return a 409 conflict error if the entity already exists — it will update the existing entity instead.

Bulk Create or Update (PUT)

Use PUT /v1/users/bulk to create or update multiple users in a single request. The request body is an array of create request objects.

curl -X PUT "{base_url}/api/v1/users/bulk" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '[
    { "name": "user_one", "email": "user_one@example.com" },
    { "name": "user_two", "email": "user_two@example.com" }
  ]'

Domains

Only administrators can set a user’s domains when creating a user with POST or PUT. Other callers, including bots, get 403. Naming no domains always works.

Allowed Email Domains

When allowedEmailDomains is set, creating a user whose email domain is not allowed returns 400 with a message that names the rejected domain and the allowed ones:

Email domain '<domain>' is not allowed. Allowed email domains: <list>

Endpoints checked: POST /api/v1/users, PUT /api/v1/users only when the request creates the user, and CSV import rows that create a user.
CSV import: A row outside the allowed domains is rejected, including in a dry run. The other rows still import, so the result status is partialSuccess. It is failure when every row is rejected.
Updates: Updating an existing user is never checked, including a PUT to a user that already exists and CSV rows that update an existing user. You cannot change a user’s email address with PATCH or PUT.
Skipped: The check does not apply to bots, to users that the server creates itself such as the bootstrap admins, or when the authentication provider is basic or openmetadata.

Error Handling

Code	Error Type	Description
`400`	`BAD_REQUEST`	Invalid request body, missing required fields, or an email domain that is not allowed
`401`	`UNAUTHORIZED`	Invalid or missing authentication token
`403`	`FORBIDDEN`	User lacks permission to create users
`409`	`ENTITY_ALREADY_EXISTS`	User with same name already exists (POST only)

API Reference

Data Assets

Collaboration

AI SDK

SDK

Discovery

Lineage

Data Contracts

Teams And Users

Data Governance

Data Quality

Alerts

Incidents

Main Concepts

Create a User

Create a User

Permissions

Body Parameters

Returns

Response

Create or Update (PUT)

Bulk Create or Update (PUT)

Domains

Allowed Email Domains

Error Handling