Skip to content
Console
Menu

Alerts and status pages

App store purchases

Credits

Knowledge

KV

Notifications

Organizations

Storage

Workflows

API reference

Getting Started

Authentication

KV Store

Attach external id on an end user

Sets the customer's own id for an end user, once: an unset namespace is written, a set one is never rewritten, and a different value for a…

Sets the customer's own id for an end user, once: an unset namespace is written, a set one is never rewritten, and a different value for a set namespace is refused. A namespace holds one id for the life of the user. Erasure removes the ids and remembers their hashes, so a value that belonged to an erased user is never handed to another one.

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

#Request

FieldTypeWhat it is
namestringThe name of the end user. Required.
namespacestringThe customer's namespace for this id: ^[a-z][a-z0-9_]{0,31}$. Required.
external_idstringThe id itself, 1 to 128 printable characters, unique in its namespace across the environment's live users. Required.

#Response

FieldTypeWhat it is
namestringorgs/{org}/projects/{project}/envs/{env}/end_users/{end_user}.
uidstringusr_<cell><ulid>; never reused. Output only.
metaResourceMetaResource metadata.
emailstringThe primary email address.
email_verify_timetimestampWhen email was verified. Output only.
passwordstringAn initial password; write-only, checked against breached passwords. Never returned again.
stateEndUserStateThe lifecycle state. Output only. One of active, suspended.
factorsAuthMethod[]Enrolled factors. Output only. One of password, magic_link, email_otp, passkey, totp, oidc, saml, device.
public_metadatastructApp data readable by the end user's own tokens.
private_metadatastructApp data readable only with an Access key.
last_login_timetimestampThe last successful sign-in. Output only.
unsafe_metadatastructApp data the end user may write with their own session (preferences a sign-up form collects); never trust it for authorization.
lock_expire_timetimestampUntil when sign-in is locked after repeated failures; unset when not locked. Unlock clears it; a suspension is state, not a lock. Output only.
external_idsmap<string, string>The customer's own ids for this end user, one per namespace (game_user, steam_id): how an app that signs users in by its own id finds them again. Read on create; never changed through here, because a set namespace's value is never rewritten — AttachEndUserExternalId sets an unset one. At most four namespaces. Never an authorization input: scope checks use grant ids.
synthetic_timetimestampWhen the end user became a test account: set once, when an end user who signed up with an address matching the Auth config's test_email_pattern first proved that address by a link or code. No update, import, address change or sign-in method ever sets it; changing the address clears it. Unset for every other end user. Output only.

#ResourceMeta

FieldTypeWhat it is
generationint64Increases by one on every change to spec. Output only.
etagstringStrong ETag (AIP-154): changes on any change to spec, status, or metadata. Send it back as If-Match or etag to make Update and Delete conditional; a mismatch fails with ABORTED / 409 ETAG_MISMATCH. Output only.
create_timetimestampWhen the Resource was created. Output only.
update_timetimestampWhen the Resource last changed. Output only.
delete_timetimestampSet while the Resource is being deleted. Output only.
labelsmap<string, string>Caller-writable, indexed labels (AIP-122 label rules).
annotationsmap<string, string>Caller-writable, unindexed annotations.
display_namestringCaller-writable human-readable name.
creatorstringThe principal that created the Resource. Output only.

#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/end-user:attachExternalId" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"…","namespace":"…"}'