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
Base URL:
https://<your-endpoint>/v1, path prefix/users.Resources:
user(user),identity(OAuth/OIDC identity),session(session),target(message target),token(short-lived Custom Token),membership(team membership, read-only view).User IDs are custom or auto-generated strings (a-z, A-Z, 0-9,
.,-,_; must not start with a special character, up to 36 characters).
Authentication and Permissions
See Common conventions for authentication and request header conventions. Scopes involved in this domain:
| scope | Covered operations |
|---|---|
users.read | Read users/identities/Sessions/logs/memberships/MFA factors |
users.write | Create and modify users, passwords, status, labels, preferences, MFA management, Session management, Token/JWT issuance, identity deletion |
targets.read / targets.write | Read 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 + path | Purpose |
|---|---|
GET /users | List users (pagination/search) |
POST /users | Create user (plaintext password) |
POST /users/argon2 | Create user by importing an Argon2 hash |
POST /users/bcrypt | Create user by importing a Bcrypt hash |
POST /users/md5 | Create user by importing an MD5 hash |
POST /users/phpass | Create user by importing a PHPass hash |
POST /users/scrypt | Create user by importing a Scrypt hash |
POST /users/scrypt-modified | Create user by importing a Scrypt Modified hash |
POST /users/sha | Create user by importing a SHA hash |
GET /users/{userId} | Get a single user |
DELETE /users/{userId} | Delete user |
PATCH /users/{userId}/email | Update email |
PATCH /users/{userId}/name | Update name |
PATCH /users/{userId}/password | Reset password (plaintext, re-hashed by the server) |
PATCH /users/{userId}/phone | Update phone number |
PATCH /users/{userId}/status | Enable/ban user |
PATCH /users/{userId}/verification | Directly set email verification status |
PATCH /users/{userId}/verification/phone | Directly set phone verification status |
PUT /users/{userId}/labels | Replace user labels wholesale |
PATCH /users/{userId}/impersonator | Set/unset user restricted identity (impersonator) capability |
GET /users/{userId}/prefs | Read user preferences |
PATCH /users/{userId}/prefs | Merge-write user preferences |
GET /users/{userId}/logs | User activity logs |
GET /users/{userId}/memberships | List of the user's team memberships |
POST /users/{userId}/tokens | Issue a short-lived Custom Token |
POST /users/{userId}/jwts | Issue a JWT for an existing Session |
GET /users/{userId}/sessions | List user Sessions |
POST /users/{userId}/sessions | Create a Session for a user |
DELETE /users/{userId}/sessions | Revoke all Sessions |
DELETE /users/{userId}/sessions/{sessionId} | Revoke a single Session |
GET /users/{userId}/mfa/factors | List MFA factors |
PATCH /users/{userId}/mfa | Toggle user MFA |
DELETE /users/{userId}/mfa/authenticators/{type} | Delete authenticator (type=totp) |
GET /users/{userId}/mfa/recovery-codes | Read recovery codes |
PATCH /users/{userId}/mfa/recovery-codes | Generate recovery codes |
PUT /users/{userId}/mfa/recovery-codes | Regenerate recovery codes |
GET /users/identities | List OAuth identities |
DELETE /users/identities/{identityId} | Delete identity |
GET /users/{userId}/targets | List message targets |
POST /users/{userId}/targets | Create 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
Labels working with permissions: after calling
PUT /v1/users/{userId}/labelsto replace the user's label array wholesale, the user immediately gains the correspondinglabel:<name>role permissions when accessing databases, storage buckets, or knowledge bases (see permission string grammar).Password import and reset: when importing users from legacy systems via endpoints such as
/users/argon2and/users/bcrypt, the platform retains the original password hash format and validates it at the user's first login; callingPATCH /v1/users/{userId}/passwordinstead passes a plaintext password, which the platform uniformly re-hashes with Argon2 for storage.
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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
queries | query | string[] | No | Default [] | 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 |
search | query | string | No | Fuzzy search term (up to 256 characters), covering name and email | |
total | query | boolean | No | Default true | Pass 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().
| Field | Type | Description |
|---|---|---|
| total | integer | Total 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | body | string | Yes | User 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 | |
email | body | string | No | Email; unique within the project, duplicates return 409 user_already_exists | |
phone | body | string | No | Phone number, starting with + including country code (E.164), e.g. +12065550100 | |
password | body | string | No | Plaintext password, at least 8 characters; hashed by the server with the project's default algorithm (Argon2) | |
name | body | string | No | Name, max length 128 characters |
Output: 201, returning the user model. Full field table:
| Field | Type | Description |
|---|---|---|
| $id | string | User ID |
| $createdAt | string | Creation time (ISO 8601) |
| $updatedAt | string | Last update time (ISO 8601) |
| name | string | Name |
| password | string? | Hashed password string (the management API never returns plaintext; when created via the hashed-import endpoint, this is the hash from the source system) |
| hash | string? | Password hashing algorithm name (argon2 / bcrypt / md5 / phpass / scrypt / scryptModified / sha) |
| hashOptions | object? | Hashing algorithm parameters (algoArgon2 / algoScrypt etc., structure corresponding to hash; e.g. Argon2 uses type/memoryCost/timeCost/threads) |
| registration | string | Registration time (ISO 8601) |
| status | boolean | Enablement status: true enabled, false banned |
| labels | string[] | User labels (basis for label:<name> permission checks) |
| passwordUpdate | string | Last password update time (ISO 8601) |
| string | Email (empty string when unset) | |
| phone | string | Phone number (E.164 format, empty string when unset) |
| emailVerification | boolean | Email verification status |
| phoneVerification | boolean | Phone verification status |
| mfa | boolean | Whether MFA is enabled |
| prefs | object | Preferences key-value object |
| targets | target[] | List of message targets (same structure as the targets endpoint) |
| accessedAt | string | Last access time (ISO 8601, not refreshed again within 24 hours) |
| impersonator | boolean? | Whether the restricted identity (impersonator) capability is present |
| impersonatorUserId | string? | 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | body | string | Yes | Same userId constraints as POST /v1/users | |
email | body | string | Yes | Email; unique within the project | |
password | body | string | Yes | Argon2 hash string from the source system (e.g. $argon2id$v=19$m=2048,t=4,p=3$...); the server stores it as-is | |
name | body | string | No | Name, 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | body | string | Yes | Same userId constraints as POST /v1/users | |
email | body | string | Yes | Email; unique within the project | |
password | body | string | Yes | Bcrypt hash string from the source system (e.g. $2a$12$...) | |
name | body | string | No | Name, 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | body | string | Yes | Same userId constraints as POST /v1/users | |
email | body | string | Yes | Email; unique within the project | |
password | body | string | Yes | MD5 hash string from the source system (32-character hex, e.g. 5f4dcc3b5aa765d61d8327deb882cf99) | |
name | body | string | No | Name, 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | body | string | Yes | Same userId constraints as POST /v1/users | |
email | body | string | Yes | Email; unique within the project | |
password | body | string | Yes | PHPass hash string from the source system (e.g. $P$B...) | |
name | body | string | No | Name, 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | body | string | Yes | Same userId constraints as POST /v1/users | |
email | body | string | Yes | Email; unique within the project | |
password | body | string | Yes | Scrypt hash string from the source system | |
passwordSalt | body | string | Yes | Salt used for hashing | |
passwordCpu | body | integer | Yes | CPU cost parameter (source system configuration) | |
passwordMemory | body | integer | Yes | Memory cost parameter (source system configuration) | |
passwordParallel | body | integer | Yes | Parallelization parameter (source system configuration) | |
passwordLength | body | integer | Yes | Hash output length (source system configuration) | |
name | body | string | No | Name, 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | body | string | Yes | Same userId constraints as POST /v1/users | |
email | body | string | Yes | Email; unique within the project | |
password | body | string | Yes | Scrypt Modified hash string from the source system (base64) | |
passwordSalt | body | string | Yes | Salt used for hashing (base64) | |
passwordSaltSeparator | body | string | Yes | Salt separator (Firebase export field saltSeparator) | |
passwordSignerKey | body | string | Yes | Signer key (Firebase export field signerKey, base64) | |
name | body | string | No | Name, 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | body | string | Yes | Same userId constraints as POST /v1/users | |
email | body | string | Yes | Email; unique within the project | |
password | body | string | Yes | SHA hash string from the source system (hex) | |
passwordVersion | body | string | No | sha1 (default) / sha224 / sha256 / sha384 / sha512/224 / sha512/256 / sha512 / sha3-224 / sha3-256 / sha3-384 / sha3-512 | SHA variant; must match the source system |
name | body | string | No | Name, 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
email | body | string | Yes | New 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.
| Field | Type | Description |
|---|---|---|
| string | Updated 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
name | body | string | Yes | New name, max length 128 characters |
Output: 200, returning user (focus on the name field). For full fields, see POST /v1/users.
| Field | Type | Description |
|---|---|---|
| name | string | Updated 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
password | body | string | Yes | New plaintext password, at least 8 characters |
Output: 200, returns user (note the passwordUpdate field is refreshed). For full fields see POST /v1/users.
| Field | Type | Description |
|---|---|---|
| passwordUpdate | string | Time 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
number | body | string | Yes | New 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.
| Field | Type | Description |
|---|---|---|
| phone | string | Updated 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
status | body | boolean | Yes | true Enable / false Ban | Target status |
Output: 200, returning user (focus on the status field). For full fields, see POST /v1/users.
| Field | Type | Description |
|---|---|---|
| status | boolean | false 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
emailVerification | body | boolean | Yes | Target verification status |
Output: 200, returning user (focus on the emailVerification field). For full fields, see POST /v1/users.
| Field | Type | Description |
|---|---|---|
| emailVerification | boolean | Email 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
phoneVerification | body | boolean | Yes | Target verification status |
Output: 200, returning user (focus on the phoneVerification field). For full fields, see POST /v1/users.
| Field | Type | Description |
|---|---|---|
| phoneVerification | boolean | Phone 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
labels | body | string[] | Yes | Up to 1000 items, each an alphanumeric string of no more than 36 characters | The complete new label array |
Output: 200, returning user (focus on the labels field). For full fields, see POST /v1/users.
| Field | Type | Description |
|---|---|---|
| labels | string[] | 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID (the user being granted the capability) | |
impersonator | body | boolean | Yes | true Enable / false Disable |
Output : 200, returns user (focus on the impersonator-related fields). See POST /v1/users for the complete fields.
| Field | Type | Description |
|---|---|---|
| impersonator | boolean | Whether the user has impersonation capability |
| impersonatorUserId | string? | 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
prefs | body | object | Yes | The 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
queries | query | string[] | No | Default [] | Only limit(n) and offset(n) methods are supported; field filtering is not supported |
total | query | boolean | No | Default true | Pass false to skip counting |
Output : 200, returns a logList model: total + logs[].
| Field | Type | Description |
|---|---|---|
| total | integer | Total number of logs |
| logs[] | log[] | Log entries, fields below |
| Field | Type | Description |
|---|---|---|
| event | string | Event name (e.g., account.sessions.create) |
| userId / userEmail / userName | string | ID/email/name of the user attributed to the action; during impersonation, the original actor is recorded rather than the impersonated user |
| mode | string | API mode at trigger time (e.g., admin) |
| ip | string | IP address at trigger time |
| time | string | Log time (ISO 8601) |
| osCode / osName / osVersion, clientType / clientCode / clientName / clientVersion / clientEngine / clientEngineVersion, deviceName / deviceBrand / deviceModel | string | Triggering device and client information (same as the session model) |
| countryCode / countryName | string | Triggering 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
queries | query | string[] | No | Default [] | Filterable fields: userId, teamId, invited, joined, confirm, roles |
search | query | string | No | Fuzzy search term (up to 256 characters) | |
total | query | boolean | No | Default true | Pass 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
length | body | integer | No | Default 6 | secret Number of characters |
expire | body | integer | No | Default 900 seconds | Validity period (seconds) |
Output : 201, returns a token model.
| Field | Type | Description |
|---|---|---|
| secret | string | Token credential (length equals length); the actual value is only returned when called with an API Key |
| expire | string | Expiration time (ISO 8601) |
| phrase | string | Security 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
sessionId | body | string | No | Default recent (most recent Session) | Target Session ID |
duration | body | integer | No | Default 900 seconds, maximum 3600 | JWT validity period (seconds) |
Output : 201, returns a jwt model.
| Field | Type | Description |
|---|---|---|
| jwt | string | The 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
total | query | boolean | No | Default true | Pass false to skip counting |
Output : 200, returns a sessionList model: total + sessions[].
| Field | Type | Description |
|---|---|---|
| total | integer | Total number of Sessions |
| sessions[] | session[] | Session objects, fields below |
| Field | Type | Description |
|---|---|---|
| $id | string | Session ID (identifier for cursor pagination and targeted revocation) |
| $createdAt / $updatedAt | string | Creation/most recent update time (ISO 8601) |
| userId | string | Owning user ID |
| expire | string | Expiration time (ISO 8601) |
| provider | string | Creation channel (e.g., email, phone, various Provider names of oauth, server, etc.) |
| providerUid / providerAccessToken / providerAccessTokenExpiry / providerRefreshToken | string | User identifier and tokens for OAuth-type channels (empty values for non-OAuth channels) |
| ip | string | IP address when the Session was created |
| osCode / osName / osVersion | string | Operating system code/name/version |
| clientType / clientCode / clientName / clientVersion | string | Client type/code/name/version |
| clientEngine / clientEngineVersion | string | Client rendering engine and version |
| deviceName / deviceBrand / deviceModel | string | Device name/brand/model |
| countryCode / countryName | string | ISO 3166-1 two-letter country code and country name |
| current | boolean | Whether this is the Session of the current request (always false from the server's perspective) |
| factors | string[] | Authentication factors that have been passed (e.g., email, totp) |
| secret | string | Session credential, returned only when the request carries an API Key |
| mfaUpdatedAt | string | Time 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
sessionId | path | string | Yes | Session 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
mfa | body | boolean | Yes | true Enable / false Disable |
Output: 200, returning user (focus on the mfa field). For full fields, see POST /v1/users.
| Field | Type | Description |
|---|---|---|
| mfa | boolean | MFA 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
type | path | string | Yes | Only totp | Authenticator 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID |
Output : 200, returns a mfaRecoveryCodes model.
| Field | Type | Description |
|---|---|---|
| recoveryCodes | string[] | 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
queries | query | string[] | No | Default [] | Filterable fields: userId, provider, providerUid, providerEmail, providerAccessTokenExpiry |
search | query | string | No | Fuzzy search term (up to 256 characters) | |
total | query | boolean | No | Default true | Pass false to skip counting |
Output : 200, returns a identityList model: total + identities[].
| Field | Type | Description |
|---|---|---|
| total | integer | Total number of identities |
| identities[] | identity[] | Identity objects; fields listed below |
| Field | Type | Description |
|---|---|---|
| $id | string | Identity ID |
| $createdAt / $updatedAt | string | Creation/update time (ISO 8601) |
| userId | string | Associated local user ID |
| provider | string | Identity provider (OAuth/OIDC provider name) |
| providerUid | string | The user's ID on the provider side |
| providerEmail | string | The user's email on the provider side |
| providerAccessToken / providerAccessTokenExpiry / providerRefreshToken | string | Provider 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
identityId | path | string | Yes | Identity 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
targetId | body | string | Yes | Target ID: custom, or pass unique(); character constraints same as user ID, up to 36 characters | |
providerType | body | string | Yes | email / sms / push | Target type |
identifier | body | string | Yes | Delivery identifier: for email targets provide an email, for sms an E.164 phone number, and for push a push token | |
providerId | body | string | No | Specifies the sending provider; if omitted, the first configured provider of the same type is used | |
name | body | string | No | Target name, up to 128 characters (e.g., Ada iPhone 12) |
Output : 201, returns a target model.
| Field | Type | Description |
|---|---|---|
| $id | string | Target ID |
| providerType / identifier / providerId | string | Echoes the creation parameters |
| expired | boolean | Whether the target has expired |
| Field | Type | Description |
|---|---|---|
| $id | string | Target ID |
| $createdAt / $updatedAt | string | Creation/update time (ISO 8601) |
| name | string | Target name |
| userId | string | Owning user ID |
| providerId | string | Provider ID used for sending |
| providerType | string | Target type: email / sms / push |
| identifier | string | Delivery identifier (email, phone number, or push token) |
| expired | boolean | Whether 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
targetId | path | string | Yes | Target 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
queries | query | string[] | No | Default [] | Filterable fields: userId, providerId, identifier, providerType |
total | query | boolean | No | Default true | Pass 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
targetId | path | string | Yes | Target ID | |
identifier | body | string | No | New delivery identifier (email / phone number / push token) | |
providerId | body | string | No | New sending provider ID | |
name | body | string | No | New 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | User ID | |
targetId | path | string | Yes | Target 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
User not found:
404+user_not_found; identity not found:user_identity_not_found; session not found:user_session_not_found; target not found:user_target_not_found.Duplicate email on user creation:
409+user_already_exists; whenPOST /usersis not passed withpassword, a passwordless user is created (a password can be set later withupdatePassword).Deleting a user cascades to delete their sessions, identities, targets, and memberships; the ID can be reused afterward, but historical logs retain the original ID.
Blocking (
status=false) takes effect immediately: all subsequent requests from that user are rejected; re-enabling does not restore revoked sessions.updateEmaildoes not automatically resetemailVerification;updateEmailVerificationmust also be called.When creating via imported hashes, the server does not validate hash format or consistency with the source system; incorrect parameters will make the user unable to log in. Verification after import is recommended.
Once issued, a token/JWT is valid for its entire lifetime; a leak means the account can be logged into. Use the session revocation endpoint to narrow exposure as needed.
Correspondence with the Server SDK
| service.method | Endpoint |
|---|---|
Users.list | GET /users |
Users.create | POST /users |
Users.createArgon2User | POST /users/argon2 |
Users.createBcryptUser | POST /users/bcrypt |
Users.createMD5User | POST /users/md5 |
Users.createPHPassUser | POST /users/phpass |
Users.createScryptUser | POST /users/scrypt |
Users.createScryptModifiedUser | POST /users/scrypt-modified |
Users.createSHAUser | POST /users/sha |
Users.get | GET /users/{userId} |
Users.delete | DELETE /users/{userId} |
Users.updateEmail | PATCH /users/{userId}/email |
Users.updateName | PATCH /users/{userId}/name |
Users.updatePassword | PATCH /users/{userId}/password |
Users.updatePhone | PATCH /users/{userId}/phone |
Users.updateStatus | PATCH /users/{userId}/status |
Users.updateEmailVerification | PATCH /users/{userId}/verification |
Users.updatePhoneVerification | PATCH /users/{userId}/verification/phone |
Users.updateLabels | PUT /users/{userId}/labels |
Users.updateImpersonator | PATCH /users/{userId}/impersonator |
Users.getPrefs | GET /users/{userId}/prefs |
Users.updatePrefs | PATCH /users/{userId}/prefs |
Users.listLogs | GET /users/{userId}/logs |
Users.listMemberships | GET /users/{userId}/memberships |
Users.createToken | POST /users/{userId}/tokens |
Users.createJWT | POST /users/{userId}/jwts |
Users.listSessions | GET /users/{userId}/sessions |
Users.createSession | POST /users/{userId}/sessions |
Users.deleteSessions | DELETE /users/{userId}/sessions |
Users.deleteSession | DELETE /users/{userId}/sessions/{sessionId} |
Users.listMfaFactors | GET /users/{userId}/mfa/factors |
Users.updateMfa | PATCH /users/{userId}/mfa |
Users.deleteMfaAuthenticator | DELETE /users/{userId}/mfa/authenticators/{type} |
Users.getMfaRecoveryCodes | GET /users/{userId}/mfa/recovery-codes |
Users.createMfaRecoveryCodes | PATCH /users/{userId}/mfa/recovery-codes |
Users.updateMfaRecoveryCodes | PUT /users/{userId}/mfa/recovery-codes |
Users.listIdentities | GET /users/identities |
Users.deleteIdentity | DELETE /users/identities/{identityId} |
Users.listTargets | GET /users/{userId}/targets |
Users.createTarget | POST /users/{userId}/targets |
Users.getTarget | GET /users/{userId}/targets/{targetId} |
Users.updateTarget | PATCH /users/{userId}/targets/{targetId} |
Users.deleteTarget | DELETE /users/{userId}/targets/{targetId} |