Skip to content
Console
On this page

Import an end user

Atomically admits an immutable bounded principal import batch.

Atomically admits an immutable bounded principal import batch.

  • Path POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/end_users:import
  • Scope auth:write
  • Effect write — a successful call changes state.
  • Collection end_users

Request

FieldTypeWhat it is
parentstringThe environment to import into. Required.
schema_versionint32Schema version of the typed principal input; must be 1. Required.
batch_idstringUnique immutable batch identity within parent; lowercase run-id syntax. Required.
key_namespacestringNamespace of the immutable source principal ID in each external_ids map. Required.
usersEndUserImportInput[]1..100 principals. Duplicate source IDs are refused, never collapsed. Required.

EndUserImportInput

FieldTypeWhat it is
external_idsmap<string, string>Immutable source identifiers keyed by namespace; must contain the batch's key_namespace. Required.
emailstringOptional email address for the imported end user.
email_verifiedboolWhether email was already verified in the source system.
phonestringOptional E.164 phone number for the imported end user.
phone_verifiedboolWhether phone was already verified in the source system.
display_namestringOptional human-readable display name for the end user.
statusstringAccount state (active or suspended); unspecified values are refused. Required.
create_timetimestampOriginal source creation timestamp for the imported end user. Required.
passwordEndUserImportPasswordOptional existing password verifier for the end user.
linksEndUserImportLink[]Federated identity provider links held by the end user.
devicesEndUserImportDevice[]Device credentials bound to the end user.
totp_secret_base32stringOptional Base32-encoded TOTP secret for MFA enrollment. Never returned again.

EndUserImportPassword

FieldTypeWhat it is
formatstringExplicit existing verifier scheme: aspnet-identity-v2, aspnet-identity-v3, bcrypt, scrypt, argon2 or pbkdf2. Never inferred from the value. Required.
valuestringEncoded password hash in the declared format. Required. Never returned again.
FieldTypeWhat it is
issuerstringOIDC issuer URL identifying the external identity provider. Required.
subjectstringSubject identifier assigned by the issuer. Required.

EndUserImportDevice

FieldTypeWhat it is
idstringSource device identifier unique to this device binding. Required.
secretstringOptional device secret; missing invokes existing weak-device rules. Never returned again.

Response

FieldTypeWhat it is
batch_idstringThe admitted batch ID.
imported_countint32Number of principals admitted in the batch (1..100).

Errors

Every error arrives in the body Errors describes.

Examples

curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/end_users:import" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"batch_id":"…","key_namespace":"…","schema_version":1,"users":[{"create_time":{},"external_ids":{},"status":"…"}]}'