Skip to content
Governance Platform

Import an external IDP user into the platform

POST
/api/v1/external-users/import
 
curl --request POST \
  --url https://localhost:8080/api/v1/external-users/import \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "externalUserId": "example", "organizationId": 1, "role": "example" }'

Import an IDP user into the platform database and optionally add them to an organization with a specified role

Authorizations

Section titled “Authorizations ”

Request Body

Section titled “Request Body ”

Import user request

Media type application/json
object
externalUserId
required
string
organizationId

Omit to import without membership

integer
role

Only applies with organizationId

string
Example generated
{
  "externalUserId": "example",
  "organizationId": 1,
  "role": "example"
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

User imported successfully

Media type application/json

The platform user created from an IDP user, and whether the import created or matched it

object
addedToOrganization
integer
displayName
string
email
string
importedAt
string format: date-time
importedFrom
string
organizationRole
string
userId
string
Example generated
{
  "addedToOrganization": 1,
  "displayName": "example",
  "email": "example",
  "importedAt": "2026-04-15T12:00:00Z",
  "importedFrom": "example",
  "organizationRole": "example",
  "userId": "example"
}

400

Section titled “400 ”

Bad Request - Invalid input

Media type application/json

Error body returned across the auth endpoints; the message is human-readable and not a stable identifier

object
error
string
error_description
string
Example 
{
  "error": "Unauthorized",
  "error_description": "Invalid token"
}

401

Section titled “401 ”

Unauthorized

Media type application/json

Error body returned across the auth endpoints; the message is human-readable and not a stable identifier

object
error
string
error_description
string
Example 
{
  "error": "Unauthorized",
  "error_description": "Invalid token"
}

403

Section titled “403 ”

Forbidden - requires Organization Owner role

Media type application/json

Error body returned across the auth endpoints; the message is human-readable and not a stable identifier

object
error
string
error_description
string
Example 
{
  "error": "Unauthorized",
  "error_description": "Invalid token"
}

404

Section titled “404 ”

User not found in IDP

Media type application/json

Error body returned across the auth endpoints; the message is human-readable and not a stable identifier

object
error
string
error_description
string
Example 
{
  "error": "Unauthorized",
  "error_description": "Invalid token"
}

409

Section titled “409 ”

Conflict - User already exists in platform

Media type application/json

Error body returned across the auth endpoints; the message is human-readable and not a stable identifier

object
error
string
error_description
string
Example 
{
  "error": "Unauthorized",
  "error_description": "Invalid token"
}

500

Section titled “500 ”

Internal server error

Media type application/json

Error body returned across the auth endpoints; the message is human-readable and not a stable identifier

object
error
string
error_description
string
Example 
{
  "error": "Unauthorized",
  "error_description": "Invalid token"
}