Docs
Contents

Users API

Full lifecycle management interfaces for user resources: creation (plaintext password or importing existing password hashes), profile and status maintenance, labels and preferences, MFA, targets (push/email/SMS channels), OAuth identities, and Session and Custom Token issuance. Login authentication flows (client-side exchange flows for email-password / OAuth / Magic URL) are out of scope for this section; the server side only provides the management and issuance interfaces on this page.

Service and resource boundaries

The Users API (/v1/users/*) is the core interface for managing the full lifecycle of end users in a project on the server side (e.g., customer accounts shown in the project such as user_zhangwei_001 and user_lina_002). It covers user creation, seamless migration import of mainstream password hashes (Argon2 / Bcrypt / MD5 / PHPass / Scrypt / SHA), setting profile and verification statuses, user labels (Labels, directly driving label:<name> permission checks), custom preferences (prefs), multi-factor authentication (MFA), message delivery targets (Targets), and server-side issuance of Custom Token / Session / JWT.

Resources and Base Paths

Authentication and Permissions

See Common conventions for authentication and request header conventions. Scopes involved in this domain:

scopeCovered operations
users.readRead users/identities/Sessions/logs/memberships/MFA factors
users.writeCreate and modify users, passwords, status, labels, preferences, MFA management, Session management, Token/JWT issuance, identity deletion
targets.read / targets.writeRead and write access to the target resource

Endpoint overview

The Users module provides 43 endpoints in total, grouped by responsibility: user creation and hash import (9), basic profile and ban/verification status maintenance (9), label and preference configuration (3), session and token issuance (6), MFA authenticator and recovery code governance (6), OAuth identity and message target management (7), and activity log and team membership queries (3).

Endpoint List

Method + pathPurpose
GET /usersList users (pagination/search)
POST /usersCreate user (plaintext password)
POST /users/argon2Create user by importing an Argon2 hash
POST /users/bcryptCreate user by importing a Bcrypt hash
POST /users/md5Create user by importing an MD5 hash
POST /users/phpassCreate user by importing a PHPass hash
POST /users/scryptCreate user by importing a Scrypt hash
POST /users/scrypt-modifiedCreate user by importing a Scrypt Modified hash
POST /users/shaCreate user by importing a SHA hash
GET /users/{userId}Get a single user
DELETE /users/{userId}Delete user
PATCH /users/{userId}/emailUpdate email
PATCH /users/{userId}/nameUpdate name
PATCH /users/{userId}/passwordReset password (plaintext, re-hashed by the server)
PATCH /users/{userId}/phoneUpdate phone number
PATCH /users/{userId}/statusEnable/ban user
PATCH /users/{userId}/verificationDirectly set email verification status
PATCH /users/{userId}/verification/phoneDirectly set phone verification status
PUT /users/{userId}/labelsReplace user labels wholesale
PATCH /users/{userId}/impersonatorSet/unset user restricted identity (impersonator) capability
GET /users/{userId}/prefsRead user preferences
PATCH /users/{userId}/prefsMerge-write user preferences
GET /users/{userId}/logsUser activity logs
GET /users/{userId}/membershipsList of the user's team memberships
POST /users/{userId}/tokensIssue a short-lived Custom Token
POST /users/{userId}/jwtsIssue a JWT for an existing Session
GET /users/{userId}/sessionsList user Sessions
POST /users/{userId}/sessionsCreate a Session for a user
DELETE /users/{userId}/sessionsRevoke all Sessions
DELETE /users/{userId}/sessions/{sessionId}Revoke a single Session
GET /users/{userId}/mfa/factorsList MFA factors
PATCH /users/{userId}/mfaToggle user MFA
DELETE /users/{userId}/mfa/authenticators/{type}Delete authenticator (type=totp)
GET /users/{userId}/mfa/recovery-codesRead recovery codes
PATCH /users/{userId}/mfa/recovery-codesGenerate recovery codes
PUT /users/{userId}/mfa/recovery-codesRegenerate recovery codes
GET /users/identitiesList OAuth identities
DELETE /users/identities/{identityId}Delete identity
GET /users/{userId}/targetsList message targets
POST /users/{userId}/targetsCreate message target
GET /users/{userId}/targets/{targetId}Get message target
PATCH /users/{userId}/targets/{targetId}Update message target
DELETE /users/{userId}/targets/{targetId}Delete message target

Endpoint details

Requests and Responses

The following sections give inputs, outputs, copyable call examples, and response examples for each endpoint. In all examples, replace <your-endpoint>, <YOUR_PROJECT_ID>, and <YOUR_API_KEY> with your endpoint, project ID, and API Key; the request bodies of the POST/PUT/PATCH examples are JSON, and field requiredness and defaults follow the Inputs table.

GET /v1/users

List all users in the project, with filtering by user attributes and fuzzy search.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
queriesquerystring[]NoDefault []Array of queries (forms like limit(25), offset(0), equal("status","true")), up to 100 entries and each up to 4096 characters; filterable fields: name, email, phone, status, passwordUpdate, registration, emailVerification, phoneVerification, labels, impersonator
searchquerystringNoFuzzy search term (up to 256 characters), covering name and email
totalquerybooleanNoDefault truePass false to skip counting; total always returns 0

Output: 200, returns userList model: total is the total number of matches, users[] is the users array. For pagination, take the $id of the last item on the previous page and use it together with cursorAfter().

FieldTypeDescription
totalintegerTotal number of users matching the query (always 0 when total=false)
users[]user[]User object, field structure described in POST /v1/users output notes

Call example:

curl \
  "https://<your-endpoint>/v1/users?queries[]=limit(25)&queries[]=offset(0)&total=false" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "total": 2,
  "users": [
    {
      "$id": "66a9d8ef00f21",
      "$createdAt": "2020-10-15T06:38:00.000+00:00",
      "$updatedAt": "2020-10-15T06:38:00.000+00:00",
      "name": "Ada Lovelace",
      "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
      "hash": "argon2",
      "hashOptions": {
        "type": "argon2",
        "memoryCost": 65536,
        "timeCost": 4,
        "threads": 3
      },
      "registration": "2020-10-15T06:38:00.000+00:00",
      "status": true,
      "labels": [
        "vip"
      ],
      "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
      "email": "ada@example.com",
      "phone": "+12065550100",
      "emailVerification": false,
      "phoneVerification": false,
      "mfa": false,
      "prefs": {
        "theme": "pink",
        "timezone": "UTC"
      },
      "targets": [],
      "accessedAt": "2020-10-15T06:38:00.000+00:00",
      "impersonator": false,
      "impersonatorUserId": null
    },
    {
      "$id": "66a9d8f111b3c",
      "$createdAt": "2020-10-15T06:38:00.000+00:00",
      "$updatedAt": "2020-10-15T06:38:00.000+00:00",
      "name": "Grace Hopper",
      "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
      "hash": "argon2",
      "hashOptions": {
        "type": "argon2",
        "memoryCost": 65536,
        "timeCost": 4,
        "threads": 3
      },
      "registration": "2020-10-15T06:38:00.000+00:00",
      "status": true,
      "labels": [],
      "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
      "email": "grace@example.com",
      "phone": "+12065550100",
      "emailVerification": false,
      "phoneVerification": false,
      "mfa": false,
      "prefs": {
        "theme": "pink",
        "timezone": "UTC"
      },
      "targets": [],
      "accessedAt": "2020-10-15T06:38:00.000+00:00",
      "impersonator": false,
      "impersonatorUserId": null
    }
  ]
}

POST /v1/users

Creates a user (the plaintext password is hashed and stored by the server). If password is not provided, a passwordless user is created; a password can be set later via PATCH /v1/users/{userId}/password.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdbodystringYesUser ID: custom, or pass unique() to have the server generate one; allowed characters are a-z, A-Z, 0-9, ., -, _; must not start with a special character, max length 36 characters
emailbodystringNoEmail; unique within the project, duplicates return 409 user_already_exists
phonebodystringNoPhone number, starting with + including country code (E.164), e.g. +12065550100
passwordbodystringNoPlaintext password, at least 8 characters; hashed by the server with the project's default algorithm (Argon2)
namebodystringNoName, max length 128 characters

Output: 201, returning the user model. Full field table:

FieldTypeDescription
$idstringUser ID
$createdAtstringCreation time (ISO 8601)
$updatedAtstringLast update time (ISO 8601)
namestringName
passwordstring?Hashed password string (the management API never returns plaintext; when created via the hashed-import endpoint, this is the hash from the source system)
hashstring?Password hashing algorithm name (argon2 / bcrypt / md5 / phpass / scrypt / scryptModified / sha)
hashOptionsobject?Hashing algorithm parameters (algoArgon2 / algoScrypt etc., structure corresponding to hash; e.g. Argon2 uses type/memoryCost/timeCost/threads)
registrationstringRegistration time (ISO 8601)
statusbooleanEnablement status: true enabled, false banned
labelsstring[]User labels (basis for label:<name> permission checks)
passwordUpdatestringLast password update time (ISO 8601)
emailstringEmail (empty string when unset)
phonestringPhone number (E.164 format, empty string when unset)
emailVerificationbooleanEmail verification status
phoneVerificationbooleanPhone verification status
mfabooleanWhether MFA is enabled
prefsobjectPreferences key-value object
targetstarget[]List of message targets (same structure as the targets endpoint)
accessedAtstringLast access time (ISO 8601, not refreshed again within 24 hours)
impersonatorboolean?Whether the restricted identity (impersonator) capability is present
impersonatorUserIdstring?Original acting user ID when the current request is in impersonation state

Call example:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "66a9d8ef00f21",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "password": "s3cret-Passw0rd",
  "name": "Ada Lovelace"
}'

Response example:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {},
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

To create an end user whose password is known, use the client registration flow instead; this endpoint targets server-side administration scenarios (e.g. an admin creating accounts on behalf of users, or syncing an external user directory).

POST /v1/users/argon2

Creates a user by importing an Argon2 hash: password pass in the Argon2 hash string from the source system; the server does not re-hash it and verifies it directly as Argon2 at login. Suitable for seamlessly migrating an existing user base to this platform.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdbodystringYesSame userId constraints as POST /v1/users
emailbodystringYesEmail; unique within the project
passwordbodystringYesArgon2 hash string from the source system (e.g. $argon2id$v=19$m=2048,t=4,p=3$...); the server stores it as-is
namebodystringNoName, max length 128 characters

Output: 201, returns user; the hash field is argon2, and hashOptions echoes back the hash parameters. For full fields see POST /v1/users.

Call example:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/argon2" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "66a9d8ef00f21",
  "email": "ada@example.com",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "name": "Ada Lovelace"
}'

Response example:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

POST /v1/users/bcrypt

Creates a user by importing a Bcrypt hash, with the same semantics as POST /v1/users/argon2.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdbodystringYesSame userId constraints as POST /v1/users
emailbodystringYesEmail; unique within the project
passwordbodystringYesBcrypt hash string from the source system (e.g. $2a$12$...)
namebodystringNoName, max length 128 characters

Output: 201, returns user; hash is bcrypt. For full fields see POST /v1/users.

Call example:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/bcrypt" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "66a9d8ef00f21",
  "email": "ada@example.com",
  "password": "$2a$12$R9h/cIPz0gi.URNNX3kh2OPST9/PgBkqquzi.Ss7KIUgO2t0jWMUW",
  "name": "Ada Lovelace"
}'

Response example:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "bcrypt",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

POST /v1/users/md5

Creates a user by importing an MD5 hash, with the same semantics as POST /v1/users/argon2. MD5 is no longer secure; after import, users should be guided to reset their passwords.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdbodystringYesSame userId constraints as POST /v1/users
emailbodystringYesEmail; unique within the project
passwordbodystringYesMD5 hash string from the source system (32-character hex, e.g. 5f4dcc3b5aa765d61d8327deb882cf99)
namebodystringNoName, max length 128 characters

Output: 201, returns user; hash is md5. For full fields see POST /v1/users.

Call example:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/md5" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "66a9d8ef00f21",
  "email": "ada@example.com",
  "password": "5f4dcc3b5aa765d61d8327deb882cf99",
  "name": "Ada Lovelace"
}'

Response example:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "md5",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

POST /v1/users/phpass

Creates a user by importing a PHPass hash (commonly used by WordPress and similar systems), with the same semantics as POST /v1/users/argon2.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdbodystringYesSame userId constraints as POST /v1/users
emailbodystringYesEmail; unique within the project
passwordbodystringYesPHPass hash string from the source system (e.g. $P$B...)
namebodystringNoName, max length 128 characters

Output: 201, returns user; hash is phpass. For full fields see POST /v1/users.

Call example:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/phpass" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "66a9d8ef00f21",
  "email": "ada@example.com",
  "password": "$P$BpB4iZ4sRoQyBfq0PfPOiZyEpX6xj.",
  "name": "Ada Lovelace"
}'

Response example:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "phpass",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

POST /v1/users/scrypt

Creates a user by importing a Scrypt hash. Scrypt verification requires the source system's full hash parameters, so in addition to the hash string you must also pass the salt and cost parameters.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdbodystringYesSame userId constraints as POST /v1/users
emailbodystringYesEmail; unique within the project
passwordbodystringYesScrypt hash string from the source system
passwordSaltbodystringYesSalt used for hashing
passwordCpubodyintegerYesCPU cost parameter (source system configuration)
passwordMemorybodyintegerYesMemory cost parameter (source system configuration)
passwordParallelbodyintegerYesParallelization parameter (source system configuration)
passwordLengthbodyintegerYesHash output length (source system configuration)
namebodystringNoName, max length 128 characters

Output: 201, returns user; hash is scrypt, and hashOptions echoes back the parameters above. For full fields see POST /v1/users.

Call example:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/scrypt" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "66a9d8ef00f21",
  "email": "ada@example.com",
  "password": "6d6c6f5f736372797074",
  "passwordSalt": "b3JpZ2luYWwtc2FsdA==",
  "passwordCpu": 1,
  "passwordMemory": 14,
  "passwordParallel": 8,
  "passwordLength": 32,
  "name": "Ada Lovelace"
}'

Response example:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "scrypt",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

POST /v1/users/scrypt-modified

Creates a user by importing a Scrypt Modified hash (Firebase Auth export format), with the same semantics as POST /v1/users/scrypt, but the parameters are the Firebase-specific salt separator and signer key.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdbodystringYesSame userId constraints as POST /v1/users
emailbodystringYesEmail; unique within the project
passwordbodystringYesScrypt Modified hash string from the source system (base64)
passwordSaltbodystringYesSalt used for hashing (base64)
passwordSaltSeparatorbodystringYesSalt separator (Firebase export field saltSeparator)
passwordSignerKeybodystringYesSigner key (Firebase export field signerKey, base64)
namebodystringNoName, max length 128 characters

Output: 201, returns user; hash is scryptModified. For full fields see POST /v1/users.

Call example:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/scrypt-modified" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "66a9d8ef00f21",
  "email": "ada@example.com",
  "password": "dHJhbnNpZW50LXBhc3N3b3Jk",
  "passwordSalt": "QUJDREVGRw==",
  "passwordSaltSeparator": "c2FsdC1zZXBhcmF0b3I=",
  "passwordSignerKey": "c2lnbmVyLWtleQ==",
  "name": "Ada Lovelace"
}'

Response example:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "scryptModified",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

POST /v1/users/sha

Creates a user by importing a hash from the SHA family, with the same semantics as POST /v1/users/argon2; use passwordVersion to specify the exact variant.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdbodystringYesSame userId constraints as POST /v1/users
emailbodystringYesEmail; unique within the project
passwordbodystringYesSHA hash string from the source system (hex)
passwordVersionbodystringNosha1 (default) / sha224 / sha256 / sha384 / sha512/224 / sha512/256 / sha512 / sha3-224 / sha3-256 / sha3-384 / sha3-512SHA variant; must match the source system
namebodystringNoName, max length 128 characters

Output: 201, returns user; hash is sha, and hashOptions echoes back the version. For full fields see POST /v1/users.

Call example:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/sha" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "66a9d8ef00f21",
  "email": "ada@example.com",
  "password": "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92",
  "passwordVersion": "sha256",
  "name": "Ada Lovelace"
}'

Response example:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "sha",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

GET /v1/users/{userId}

Gets a single user by ID.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID

Output: 200, returns the user model; for full fields see POST /v1/users.

Call example:

curl \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

DELETE /v1/users/{userId}

Deletes a user. Cascades to delete all of their sessions, OAuth identities, message targets, and team member relationships; the ID becomes reusable after deletion, while historical logs retain the original ID for auditing.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID

Output: 204 No Content, no response body.

Call example:

curl \
  -X DELETE \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

PATCH /v1/users/{userId}/email

Updates the user's email. This does not automatically update emailVerification — if the verification status should remain valid, call PATCH /v1/users/{userId}/verification afterwards.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
emailbodystringYesNew email; conflicts with another user return 409 user_already_exists

Output: 200, returning user (focus on the email field). For full fields, see POST /v1/users.

FieldTypeDescription
emailstringUpdated email

Call example:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/email" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ada-new@example.com"
}'

Response example:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada-new@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

PATCH /v1/users/{userId}/name

Updates the user's name.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
namebodystringYesNew name, max length 128 characters

Output: 200, returning user (focus on the name field). For full fields, see POST /v1/users.

FieldTypeDescription
namestringUpdated name

Call example:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/name" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ada King"
}'

Response example:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada King",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

PATCH /v1/users/{userId}/password

Resets the user's password (the server re-hashes it from plaintext). None of the user's existing sessions are automatically revoked; to force sign-out, call DELETE /v1/users/{userId}/sessions.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
passwordbodystringYesNew plaintext password, at least 8 characters

Output: 200, returns user (note the passwordUpdate field is refreshed). For full fields see POST /v1/users.

FieldTypeDescription
passwordUpdatestringTime of this reset (ISO 8601)

Call example:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/password" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "password": "n3w-Secret-Pass"
}'

Response example:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

PATCH /v1/users/{userId}/phone

Updates the user's phone number.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
numberbodystringYesNew phone number, including country code at the start (E.164) +

Output: 200, returning user (focus on the phone field). For full fields, see POST /v1/users.

FieldTypeDescription
phonestringUpdated phone number

Call example:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/phone" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "+8613800138000"
}'

Response example:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+8613800138000",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

PATCH /v1/users/{userId}/status

Enable or ban a user. Bans take effect immediately: all subsequent requests from the user are rejected; re-enabling the user does not restore Sessions that were revoked during the ban period.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
statusbodybooleanYestrue Enable / false BanTarget status

Output: 200, returning user (focus on the status field). For full fields, see POST /v1/users.

FieldTypeDescription
statusbooleanfalse Indicates banned

Call example:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/status" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "status": false
}'

Response example:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": false,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

PATCH /v1/users/{userId}/verification

Directly set/clear the email verification status (server-side admin action; no verification email is sent).

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
emailVerificationbodybooleanYesTarget verification status

Output: 200, returning user (focus on the emailVerification field). For full fields, see POST /v1/users.

FieldTypeDescription
emailVerificationbooleanEmail verification status after being set

Call example:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/verification" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "emailVerification": true
}'

Response example:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": true,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

PATCH /v1/users/{userId}/verification/phone

Directly set/clear the phone verification status (server-side admin action; no verification SMS is sent).

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
phoneVerificationbodybooleanYesTarget verification status

Output: 200, returning user (focus on the phoneVerification field). For full fields, see POST /v1/users.

FieldTypeDescription
phoneVerificationbooleanPhone verification status after being set

Call example:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/verification/phone" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneVerification": true
}'

Response example:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": true,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

PUT /v1/users/{userId}/labels

Replace the user labels entirely. Labels are the basis for evaluating label:<name> permission strings (see permissions) and also serve as list filtering fields; this endpoint uses full-replacement semantics, so labels not listed are removed.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
labelsbodystring[]YesUp to 1000 items, each an alphanumeric string of no more than 36 charactersThe complete new label array

Output: 200, returning user (focus on the labels field). For full fields, see POST /v1/users.

FieldTypeDescription
labelsstring[]Label array after replacement

Call example:

curl \
  -X PUT \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/labels" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "labels": [
    "vip",
    "beta-tester"
  ]
}'

Response example:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip",
    "beta-tester"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

PATCH /v1/users/{userId}/impersonator

Set/clear the user's restricted identity (impersonator) capability. When set to true, the user may carry the X-Appwrite-Impersonate-User-Id / X-Appwrite-Impersonate-User-Email headers in client contexts to perform authenticated requests as a target user within the project (support and proxy-operation scenarios). Note: impersonation headers are only effective when the request itself is already authenticated as some user; carrying only X-Appwrite-Key is insufficient to enable it; audit logs always attribute actions to the original actor.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID (the user being granted the capability)
impersonatorbodybooleanYestrue Enable / false Disable

Output : 200, returns user (focus on the impersonator-related fields). See POST /v1/users for the complete fields.

FieldTypeDescription
impersonatorbooleanWhether the user has impersonation capability
impersonatorUserIdstring?Returned only when the current request is in impersonation state: the original actor's user ID

Call example:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/impersonator" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "impersonator": true
}'

Response example:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": true,
  "impersonatorUserId": null
}

GET /v1/users/{userId}/prefs

Read user preferences (free-form key-value JSON whose semantics are defined by the business side, such as theme, timezone, notification toggles).

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID

Output: 200, returns a preferences key-value object.

Call example:

curl \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/prefs" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "theme": "pink",
  "timezone": "UTC"
}

PATCH /v1/users/{userId}/prefs

Merge-write user preferences: shallow merge, same keys are overwritten, other keys are preserved.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
prefsbodyobjectYesThe key-value object to write

Output : 200, returns the merged preferences object.

Call example:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/prefs" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "prefs": {
    "theme": "dark"
  }
}'

Response example:

{
  "theme": "dark",
  "timezone": "UTC"
}

GET /v1/users/{userId}/logs

List the user's activity logs (login, authentication changes, and other events triggered by the user) for security auditing.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
queriesquerystring[]NoDefault []Only limit(n) and offset(n) methods are supported; field filtering is not supported
totalquerybooleanNoDefault truePass false to skip counting

Output : 200, returns a logList model: total + logs[].

FieldTypeDescription
totalintegerTotal number of logs
logs[]log[]Log entries, fields below
FieldTypeDescription
eventstringEvent name (e.g., account.sessions.create)
userId / userEmail / userNamestringID/email/name of the user attributed to the action; during impersonation, the original actor is recorded rather than the impersonated user
modestringAPI mode at trigger time (e.g., admin)
ipstringIP address at trigger time
timestringLog time (ISO 8601)
osCode / osName / osVersion, clientType / clientCode / clientName / clientVersion / clientEngine / clientEngineVersion, deviceName / deviceBrand / deviceModelstringTriggering device and client information (same as the session model)
countryCode / countryNamestringTriggering geography (ISO 3166-1 country code and country name)

Call example:

curl \
  'https://<your-endpoint>/v1/users/66a9d8ef00f21/logs?queries[]=limit(25)&queries[]=offset(0)' \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "total": 1,
  "logs": [
    {
      "event": "account.sessions.create",
      "userId": "66a9d8ef00f21",
      "userEmail": "ada@example.com",
      "userName": "Ada Lovelace",
      "mode": "admin",
      "ip": "192.168.1.1",
      "time": "2020-10-15T06:38:00.000+00:00",
      "osCode": "Mac",
      "osName": "Mac",
      "osVersion": "10.15.6",
      "clientType": "browser",
      "clientCode": "CH",
      "clientName": "Chrome",
      "clientVersion": "84.0",
      "clientEngine": "Blink",
      "clientEngineVersion": "84.0",
      "deviceName": "desktop",
      "deviceBrand": "Apple",
      "deviceModel": "MacBook Pro",
      "countryCode": "CN",
      "countryName": "China"
    }
  ]
}

GET /v1/users/{userId}/memberships

List the user's memberships across all teams (read-only view); use it to troubleshoot team permissions from the user dimension. The same data on the team side is found at teams.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
queriesquerystring[]NoDefault []Filterable fields: userId, teamId, invited, joined, confirm, roles
searchquerystringNoFuzzy search term (up to 256 characters)
totalquerybooleanNoDefault truePass false to skip counting

Output : 200, returns a membershipList model: total + memberships[]. See teams for the membership field structure.

Call example:

curl \
  'https://<your-endpoint>/v1/users/66a9d8ef00f21/memberships?queries[]=limit(25)&total=false' \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "total": 1,
  "memberships": [
    {
      "$id": "66a9d94f00e3d",
      "$createdAt": "2020-10-15T06:38:00.000+00:00",
      "$updatedAt": "2020-10-15T06:38:00.000+00:00",
      "userId": "66a9d8ef00f21",
      "userName": "Ada Lovelace",
      "userEmail": "ada@example.com",
      "teamId": "66a9d93000b1a",
      "teamName": "Platform",
      "invited": "2020-10-15T06:38:00.000+00:00",
      "joined": "2020-10-15T06:38:00.000+00:00",
      "confirm": false,
      "mfa": false,
      "roles": [
        "owner"
      ]
    }
  ]
}

POST /v1/users/{userId}/tokens

Issue a short-lived Custom Token (OTP form) for the user. secret allows clients to exchange the token for a Session via the "token for Session" flow (the client-side flow is not in this directory); the server can also use it to implement custom verification code channels.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
lengthbodyintegerNoDefault 6secret Number of characters
expirebodyintegerNoDefault 900 secondsValidity period (seconds)

Output : 201, returns a token model.

FieldTypeDescription
secretstringToken credential (length equals length); the actual value is only returned when called with an API Key
expirestringExpiration time (ISO 8601)
phrasestringSecurity phrase (empty string when no phrase was requested for this endpoint)

Call example:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/tokens" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "length": 6,
  "expire": 900
}'

Response example:

{
  "$id": "bb8ea5c16897e",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "userId": "66a9d8ef00f21",
  "secret": "842716",
  "expire": "2020-10-15T06:38:00.000+00:00",
  "phrase": "Golden Fox"
}

POST /v1/users/{userId}/jwts

Issue a JWT for the user's existing Session, used to pass authentication in environments that do not support Cookies (mobile apps, third-party APIs).

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
sessionIdbodystringNoDefault recent (most recent Session)Target Session ID
durationbodyintegerNoDefault 900 seconds, maximum 3600JWT validity period (seconds)

Output : 201, returns a jwt model.

FieldTypeDescription
jwtstringThe encoded JWT string

Call example:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/jwts" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "sessionId": "66a9d9a5003c2",
  "duration": 900
}'

Response example:

{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

GET /v1/users/{userId}/sessions

List all of the user's Sessions (multi-device login view); use it to audit anomalous logins or perform targeted revocation.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
totalquerybooleanNoDefault truePass false to skip counting

Output : 200, returns a sessionList model: total + sessions[].

FieldTypeDescription
totalintegerTotal number of Sessions
sessions[]session[]Session objects, fields below
FieldTypeDescription
$idstringSession ID (identifier for cursor pagination and targeted revocation)
$createdAt / $updatedAtstringCreation/most recent update time (ISO 8601)
userIdstringOwning user ID
expirestringExpiration time (ISO 8601)
providerstringCreation channel (e.g., email, phone, various Provider names of oauth, server, etc.)
providerUid / providerAccessToken / providerAccessTokenExpiry / providerRefreshTokenstringUser identifier and tokens for OAuth-type channels (empty values for non-OAuth channels)
ipstringIP address when the Session was created
osCode / osName / osVersionstringOperating system code/name/version
clientType / clientCode / clientName / clientVersionstringClient type/code/name/version
clientEngine / clientEngineVersionstringClient rendering engine and version
deviceName / deviceBrand / deviceModelstringDevice name/brand/model
countryCode / countryNamestringISO 3166-1 two-letter country code and country name
currentbooleanWhether this is the Session of the current request (always false from the server's perspective)
factorsstring[]Authentication factors that have been passed (e.g., email, totp)
secretstringSession credential, returned only when the request carries an API Key
mfaUpdatedAtstringTime of the most recent successful MFA challenge (ISO 8601)

Call example:

curl \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/sessions" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "total": 1,
  "sessions": [
    {
      "$id": "66a9d9a5003c2",
      "$createdAt": "2020-10-15T06:38:00.000+00:00",
      "$updatedAt": "2020-10-15T06:38:00.000+00:00",
      "userId": "66a9d8ef00f21",
      "expire": "2020-10-15T06:38:00.000+00:00",
      "provider": "email",
      "providerUid": "ada@example.com",
      "providerAccessToken": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
      "providerAccessTokenExpiry": "2020-10-15T06:38:00.000+00:00",
      "providerRefreshToken": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
      "ip": "192.168.1.1",
      "osCode": "Mac",
      "osName": "Mac",
      "osVersion": "10.15.6",
      "clientType": "browser",
      "clientCode": "CH",
      "clientName": "Chrome",
      "clientVersion": "84.0",
      "clientEngine": "Blink",
      "clientEngineVersion": "84.0",
      "deviceName": "desktop",
      "deviceBrand": "Apple",
      "deviceModel": "MacBook Pro",
      "countryCode": "CN",
      "countryName": "China",
      "current": false,
      "factors": [
        "email"
      ],
      "secret": "aWtUMlRDMzlNZUpDZ1BQSkRPVUtHUG9SWmh1RlhtdVo=",
      "mfaUpdatedAt": "2020-10-15T06:38:00.000+00:00"
    }
  ]
}

POST /v1/users/{userId}/sessions

Directly create a Session for the user (server-side login, no password verification) — use it when internal tools need to establish a session on a user's behalf or to test multi-device behavior; regular logins go through the client authentication flow.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID

Output : 201, returns a session model; see GET /v1/users/{userId}/sessions for the field structure.

Call example:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/sessions" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "$id": "66a9d9a5003c2",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "userId": "66a9d8ef00f21",
  "expire": "2020-10-15T06:38:00.000+00:00",
  "provider": "server",
  "providerUid": "ada@example.com",
  "providerAccessToken": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
  "providerAccessTokenExpiry": "2020-10-15T06:38:00.000+00:00",
  "providerRefreshToken": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
  "ip": "192.168.1.1",
  "osCode": "Mac",
  "osName": "Mac",
  "osVersion": "10.15.6",
  "clientType": "browser",
  "clientCode": "CH",
  "clientName": "Chrome",
  "clientVersion": "84.0",
  "clientEngine": "Blink",
  "clientEngineVersion": "84.0",
  "deviceName": "desktop",
  "deviceBrand": "Apple",
  "deviceModel": "MacBook Pro",
  "countryCode": "CN",
  "countryName": "China",
  "current": false,
  "factors": [
    "email"
  ],
  "secret": "aWtUMlRDMzlNZUpDZ1BQSkRPVUtHUG9SWmh1RlhtdVo=",
  "mfaUpdatedAt": "2020-10-15T06:38:00.000+00:00"
}

DELETE /v1/users/{userId}/sessions

Revoke all of the user's Sessions (force logout on all devices). Often used together with password reset.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID

Output: 204 No Content, no response body.

Call example:

curl \
  -X DELETE \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/sessions" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

DELETE /v1/users/{userId}/sessions/{sessionId}

Revoke a single Session of the user (logout on one device, e.g., a lost device scenario).

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
sessionIdpathstringYesSession ID (from the session list)

Output: 204 No Content, no response body.

Call example:

curl \
  -X DELETE \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/sessions/66a9d9a5003c2" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

GET /v1/users/{userId}/mfa/factors

List the user's configured MFA factors.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID

Output : 200, returns a mfaFactors model.

Call example:

curl \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/mfa/factors" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "totp": true,
  "phone": true,
  "email": true,
  "recoveryCode": true
}

PATCH /v1/users/{userId}/mfa

Turn the user's MFA on or off entirely. After turning it off, the user's logins no longer require a second factor, but the configured authenticators and recovery codes are retained.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
mfabodybooleanYestrue Enable / false Disable

Output: 200, returning user (focus on the mfa field). For full fields, see POST /v1/users.

FieldTypeDescription
mfabooleanMFA status after being set

Call example:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/mfa" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "mfa": false
}'

Response example:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

DELETE /v1/users/{userId}/mfa/authenticators/{type}

Delete the user's TOTP authenticator; the user must then re-bind TOTP or switch to another factor.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
typepathstringYesOnly totpAuthenticator type

Output: 204 No Content, no response body.

Call example:

curl \
  -X DELETE \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/mfa/authenticators/totp" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

GET /v1/users/{userId}/mfa/recovery-codes

Read the user's currently valid MFA recovery codes.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID

Output : 200, returns a mfaRecoveryCodes model.

FieldTypeDescription
recoveryCodesstring[]Array of recovery codes, each usable only once

Call example:

curl \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/mfa/recovery-codes" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "recoveryCodes": [
    "a3kf0-s0cl2",
    "s0co1-as98s"
  ]
}

PATCH /v1/users/{userId}/mfa/recovery-codes

Generate MFA recovery codes for the first time (if they already exist, 409 is returned; use PUT to regenerate instead).

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID

Output : 201, returns a mfaRecoveryCodes model.

Call example:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/mfa/recovery-codes" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "recoveryCodes": [
    "a3kf0-s0cl2",
    "s0co1-as98s"
  ]
}

PUT /v1/users/{userId}/mfa/recovery-codes

Regenerate MFA recovery codes and fully overwrite the old ones (all old codes become invalid).

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID

Output : 200, returns a mfaRecoveryCodes model.

Call example:

curl \
  -X PUT \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/mfa/recovery-codes" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "recoveryCodes": [
    "zx1v2-k4m5n",
    "q7w8e-r9t0y"
  ]
}

GET /v1/users/identities

Lists all OAuth/OIDC identities within the project (a cross-user view of third-party login bindings), for troubleshooting issues such as "the same third-party account being bound to multiple users".

Input:

ParameterLocationTypeRequiredDefault/enumDescription
queriesquerystring[]NoDefault []Filterable fields: userId, provider, providerUid, providerEmail, providerAccessTokenExpiry
searchquerystringNoFuzzy search term (up to 256 characters)
totalquerybooleanNoDefault truePass false to skip counting

Output : 200, returns a identityList model: total + identities[].

FieldTypeDescription
totalintegerTotal number of identities
identities[]identity[]Identity objects; fields listed below
FieldTypeDescription
$idstringIdentity ID
$createdAt / $updatedAtstringCreation/update time (ISO 8601)
userIdstringAssociated local user ID
providerstringIdentity provider (OAuth/OIDC provider name)
providerUidstringThe user's ID on the provider side
providerEmailstringThe user's email on the provider side
providerAccessToken / providerAccessTokenExpiry / providerRefreshTokenstringProvider access token, expiry time, and refresh token

Call example:

curl \
  'https://<your-endpoint>/v1/users/identities?queries[]=limit(25)&queries[]=equal("provider","github")&total=false' \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "total": 1,
  "identities": [
    {
      "$id": "66a9d96700f4e",
      "$createdAt": "2020-10-15T06:38:00.000+00:00",
      "$updatedAt": "2020-10-15T06:38:00.000+00:00",
      "userId": "66a9d8ef00f21",
      "provider": "github",
      "providerUid": "10241284",
      "providerEmail": "ada@example.com",
      "providerAccessToken": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
      "providerAccessTokenExpiry": "2020-10-15T06:38:00.000+00:00",
      "providerRefreshToken": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3"
    }
  ]
}

DELETE /v1/users/identities/{identityId}

Deletes an OAuth identity binding. After deletion, the user can no longer log in with the corresponding third-party account (local credentials are unaffected).

Input:

ParameterLocationTypeRequiredDefault/enumDescription
identityIdpathstringYesIdentity ID (from the identity list)

Output: 204 No Content, no response body.

Call example:

curl \
  -X DELETE \
  "https://<your-endpoint>/v1/users/identities/66a9d96700f4e" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

POST /v1/users/{userId}/targets

Creates a user messaging target (a delivery endpoint for an email address, phone number, or push token) for use by the messaging service; a user can have multiple targets.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
targetIdbodystringYesTarget ID: custom, or pass unique(); character constraints same as user ID, up to 36 characters
providerTypebodystringYesemail / sms / pushTarget type
identifierbodystringYesDelivery identifier: for email targets provide an email, for sms an E.164 phone number, and for push a push token
providerIdbodystringNoSpecifies the sending provider; if omitted, the first configured provider of the same type is used
namebodystringNoTarget name, up to 128 characters (e.g., Ada iPhone 12)

Output : 201, returns a target model.

FieldTypeDescription
$idstringTarget ID
providerType / identifier / providerIdstringEchoes the creation parameters
expiredbooleanWhether the target has expired
FieldTypeDescription
$idstringTarget ID
$createdAt / $updatedAtstringCreation/update time (ISO 8601)
namestringTarget name
userIdstringOwning user ID
providerIdstringProvider ID used for sending
providerTypestringTarget type: email / sms / push
identifierstringDelivery identifier (email, phone number, or push token)
expiredbooleanWhether the target has expired (e.g., a push token deprecated by the client)

Call example:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/targets" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "targetId": "66a9d97e01a5b",
  "providerType": "email",
  "identifier": "ada@example.com",
  "providerId": "sendgrid",
  "name": "Ada iPhone 12"
}'

Response example:

{
  "$id": "66a9d97e01a5b",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada iPhone 12",
  "userId": "66a9d8ef00f21",
  "providerId": "sendgrid",
  "providerType": "email",
  "identifier": "ada@example.com",
  "expired": false
}

GET /v1/users/{userId}/targets/{targetId}

Gets a user messaging target by ID.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
targetIdpathstringYesTarget ID

Output: 200, returning the target model; see fields in POST /v1/users/{userId}/targets.

Call example:

curl \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/targets/66a9d97e01a5b" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "$id": "66a9d97e01a5b",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada iPhone 12",
  "userId": "66a9d8ef00f21",
  "providerId": "sendgrid",
  "providerType": "email",
  "identifier": "ada@example.com",
  "expired": false
}

GET /v1/users/{userId}/targets

Lists a user's messaging targets.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
queriesquerystring[]NoDefault []Filterable fields: userId, providerId, identifier, providerType
totalquerybooleanNoDefault truePass false to skip counting

Output: 200, returning the targetList model: total + targets[]. The target fields are listed in POST /v1/users/{userId}/targets.

Call example:

curl \
  'https://<your-endpoint>/v1/users/66a9d8ef00f21/targets?queries[]=limit(25)&total=false' \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "total": 1,
  "targets": [
    {
      "$id": "66a9d97e01a5b",
      "$createdAt": "2020-10-15T06:38:00.000+00:00",
      "$updatedAt": "2020-10-15T06:38:00.000+00:00",
      "name": "Ada iPhone 12",
      "userId": "66a9d8ef00f21",
      "providerId": "sendgrid",
      "providerType": "email",
      "identifier": "ada@example.com",
      "expired": false
    }
  ]
}

PATCH /v1/users/{userId}/targets/{targetId}

Updates a user messaging target (rebind the delivery identifier, change the sending provider, or rename).

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
targetIdpathstringYesTarget ID
identifierbodystringNoNew delivery identifier (email / phone number / push token)
providerIdbodystringNoNew sending provider ID
namebodystringNoNew name, up to 128 characters

Output : 200, returns a target model.

Call example:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/targets/66a9d97e01a5b" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "identifier": "ada-new@example.com"
}'

Response example:

{
  "$id": "66a9d97e01a5b",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada iPhone 12",
  "userId": "66a9d8ef00f21",
  "providerId": "sendgrid",
  "providerType": "email",
  "identifier": "ada-new@example.com",
  "expired": false
}

DELETE /v1/users/{userId}/targets/{targetId}

Deletes a user messaging target (e.g., cleanup after a push token becomes invalid).

Input:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYesUser ID
targetIdpathstringYesTarget ID

Output: 204 No Content, no response body.

Call example:

curl \
  -X DELETE \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/targets/66a9d97e01a5b" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Errors and boundaries

Correspondence with the Server SDK

service.methodEndpoint
Users.listGET /users
Users.createPOST /users
Users.createArgon2UserPOST /users/argon2
Users.createBcryptUserPOST /users/bcrypt
Users.createMD5UserPOST /users/md5
Users.createPHPassUserPOST /users/phpass
Users.createScryptUserPOST /users/scrypt
Users.createScryptModifiedUserPOST /users/scrypt-modified
Users.createSHAUserPOST /users/sha
Users.getGET /users/{userId}
Users.deleteDELETE /users/{userId}
Users.updateEmailPATCH /users/{userId}/email
Users.updateNamePATCH /users/{userId}/name
Users.updatePasswordPATCH /users/{userId}/password
Users.updatePhonePATCH /users/{userId}/phone
Users.updateStatusPATCH /users/{userId}/status
Users.updateEmailVerificationPATCH /users/{userId}/verification
Users.updatePhoneVerificationPATCH /users/{userId}/verification/phone
Users.updateLabelsPUT /users/{userId}/labels
Users.updateImpersonatorPATCH /users/{userId}/impersonator
Users.getPrefsGET /users/{userId}/prefs
Users.updatePrefsPATCH /users/{userId}/prefs
Users.listLogsGET /users/{userId}/logs
Users.listMembershipsGET /users/{userId}/memberships
Users.createTokenPOST /users/{userId}/tokens
Users.createJWTPOST /users/{userId}/jwts
Users.listSessionsGET /users/{userId}/sessions
Users.createSessionPOST /users/{userId}/sessions
Users.deleteSessionsDELETE /users/{userId}/sessions
Users.deleteSessionDELETE /users/{userId}/sessions/{sessionId}
Users.listMfaFactorsGET /users/{userId}/mfa/factors
Users.updateMfaPATCH /users/{userId}/mfa
Users.deleteMfaAuthenticatorDELETE /users/{userId}/mfa/authenticators/{type}
Users.getMfaRecoveryCodesGET /users/{userId}/mfa/recovery-codes
Users.createMfaRecoveryCodesPATCH /users/{userId}/mfa/recovery-codes
Users.updateMfaRecoveryCodesPUT /users/{userId}/mfa/recovery-codes
Users.listIdentitiesGET /users/identities
Users.deleteIdentityDELETE /users/identities/{identityId}
Users.listTargetsGET /users/{userId}/targets
Users.createTargetPOST /users/{userId}/targets
Users.getTargetGET /users/{userId}/targets/{targetId}
Users.updateTargetPATCH /users/{userId}/targets/{targetId}
Users.deleteTargetDELETE /users/{userId}/targets/{targetId}