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
| Field | Type | What it is |
|---|---|---|
parent | string | The environment to import into. Required. |
schema_version | int32 | Schema version of the typed principal input; must be 1. Required. |
batch_id | string | Unique immutable batch identity within parent; lowercase run-id syntax. Required. |
key_namespace | string | Namespace of the immutable source principal ID in each external_ids map. Required. |
users | EndUserImportInput[] | 1..100 principals. Duplicate source IDs are refused, never collapsed. Required. |
EndUserImportInput
| Field | Type | What it is |
|---|---|---|
external_ids | map<string, string> | Immutable source identifiers keyed by namespace; must contain the batch's key_namespace. Required. |
email | string | Optional email address for the imported end user. |
email_verified | bool | Whether email was already verified in the source system. |
phone | string | Optional E.164 phone number for the imported end user. |
phone_verified | bool | Whether phone was already verified in the source system. |
display_name | string | Optional human-readable display name for the end user. |
status | string | Account state (active or suspended); unspecified values are refused. Required. |
create_time | timestamp | Original source creation timestamp for the imported end user. Required. |
password | EndUserImportPassword | Optional existing password verifier for the end user. |
links | EndUserImportLink[] | Federated identity provider links held by the end user. |
devices | EndUserImportDevice[] | Device credentials bound to the end user. |
totp_secret_base32 | string | Optional Base32-encoded TOTP secret for MFA enrollment. Never returned again. |
EndUserImportPassword
| Field | Type | What it is |
|---|---|---|
format | string | Explicit existing verifier scheme: aspnet-identity-v2, aspnet-identity-v3, bcrypt, scrypt, argon2 or pbkdf2. Never inferred from the value. Required. |
value | string | Encoded password hash in the declared format. Required. Never returned again. |
EndUserImportLink
| Field | Type | What it is |
|---|---|---|
issuer | string | OIDC issuer URL identifying the external identity provider. Required. |
subject | string | Subject identifier assigned by the issuer. Required. |
EndUserImportDevice
| Field | Type | What it is |
|---|---|---|
id | string | Source device identifier unique to this device binding. Required. |
secret | string | Optional device secret; missing invokes existing weak-device rules. Never returned again. |
Response
| Field | Type | What it is |
|---|---|---|
batch_id | string | The admitted batch ID. |
imported_count | int32 | Number of principals admitted in the batch (1..100). |
Errors
UNAUTHENTICATED— No valid key or token was presented.PERMISSION_DENIED— The key lacks the method's permission.INVALID_FIELD— A field failed validation.INVALID_STATE— The Resource is in a state that forbids the call.RESOURCE_ALREADY_EXISTS— A Resource with this name exists.
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":"…"}]}'