Go to Console
Star on GitHub 45.1K Get started

Users

SERVER

The Users service allows you to manage your project users. Use this service to search, block, and view your users' info, current sessions, and latest activity logs. You can also use the Users service to edit your users' preferences and personal info.

Base URL
https://cloud.appwrite.io/v1

List users

Get a list of all the project's users. You can use the query params to filter your results.

  • Request
    • queries array

      Array of query strings generated using the Query class provided by the SDK. Learn more about queries. Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: name, email, phone, status, passwordUpdate, registration, emailVerification, phoneVerification, labels

    • search string

      Search term to filter your list results. Max length: 256 chars.

  • Response
Endpoint
GET /users
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.list(
    queries = listOf(), // optional
    search = "<SEARCH>" // optional
)

Create user

Create a new user.

  • Request
    • userId string
      required

      User ID. Choose a custom ID or generate a random ID with ID.unique(). Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.

    • email string

      User email.

    • phone string

      Phone number. Format this number with a leading '+' and a country code, e.g., +16175551212.

    • password string

      Plain text user password. Must be at least 8 chars.

    • name string

      User name. Max length: 128 chars.

  • Response
    • 201 application/json
Endpoint
POST /users
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.create(
    userId = "<USER_ID>",
    email = "email@example.com", // optional
    phone = "+12065550100", // optional
    password = "", // optional
    name = "<NAME>" // optional
)

Create user with Argon2 password

Create a new user. Password provided must be hashed with the Argon2 algorithm. Use the POST /users endpoint to create users with a plain text password.

  • Request
    • userId string
      required

      User ID. Choose a custom ID or generate a random ID with ID.unique(). Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.

    • email string
      required

      User email.

    • password string
      required

      User password hashed using Argon2.

    • name string

      User name. Max length: 128 chars.

  • Response
    • 201 application/json
Endpoint
POST /users/argon2
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.createArgon2User(
    userId = "<USER_ID>",
    email = "email@example.com",
    password = "password",
    name = "<NAME>" // optional
)

Create user with bcrypt password

Create a new user. Password provided must be hashed with the Bcrypt algorithm. Use the POST /users endpoint to create users with a plain text password.

  • Request
    • userId string
      required

      User ID. Choose a custom ID or generate a random ID with ID.unique(). Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.

    • email string
      required

      User email.

    • password string
      required

      User password hashed using Bcrypt.

    • name string

      User name. Max length: 128 chars.

  • Response
    • 201 application/json
Endpoint
POST /users/bcrypt
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.createBcryptUser(
    userId = "<USER_ID>",
    email = "email@example.com",
    password = "password",
    name = "<NAME>" // optional
)

List identities

Get identities for all users.

  • Request
    • queries array

      Array of query strings generated using the Query class provided by the SDK. Learn more about queries. Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: userId, provider, providerUid, providerEmail, providerAccessTokenExpiry

    • search string

      Search term to filter your list results. Max length: 256 chars.

  • Response
Endpoint
GET /users/identities
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.listIdentities(
    queries = listOf(), // optional
    search = "<SEARCH>" // optional
)

Delete identity

Delete an identity by its unique ID.

  • Request
    • identityId string
      required

      Identity ID.

  • Response
    • 204 application/json
Endpoint
DELETE /users/identities/{identityId}
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.deleteIdentity(
    identityId = "<IDENTITY_ID>"
)

Create user with MD5 password

Create a new user. Password provided must be hashed with the MD5 algorithm. Use the POST /users endpoint to create users with a plain text password.

  • Request
    • userId string
      required

      User ID. Choose a custom ID or generate a random ID with ID.unique(). Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.

    • email string
      required

      User email.

    • password string
      required

      User password hashed using MD5.

    • name string

      User name. Max length: 128 chars.

  • Response
    • 201 application/json
Endpoint
POST /users/md5
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.createMD5User(
    userId = "<USER_ID>",
    email = "email@example.com",
    password = "password",
    name = "<NAME>" // optional
)

Create user with PHPass password

Create a new user. Password provided must be hashed with the PHPass algorithm. Use the POST /users endpoint to create users with a plain text password.

  • Request
    • userId string
      required

      User ID. Choose a custom ID or pass the string ID.unique()to auto generate it. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.

    • email string
      required

      User email.

    • password string
      required

      User password hashed using PHPass.

    • name string

      User name. Max length: 128 chars.

  • Response
    • 201 application/json
Endpoint
POST /users/phpass
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.createPHPassUser(
    userId = "<USER_ID>",
    email = "email@example.com",
    password = "password",
    name = "<NAME>" // optional
)

Create user with Scrypt password

Create a new user. Password provided must be hashed with the Scrypt algorithm. Use the POST /users endpoint to create users with a plain text password.

  • Request
    • userId string
      required

      User ID. Choose a custom ID or generate a random ID with ID.unique(). Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.

    • email string
      required

      User email.

    • password string
      required

      User password hashed using Scrypt.

    • passwordSalt string
      required

      Optional salt used to hash password.

    • passwordCpu integer
      required

      Optional CPU cost used to hash password.

    • passwordMemory integer
      required

      Optional memory cost used to hash password.

    • passwordParallel integer
      required

      Optional parallelization cost used to hash password.

    • passwordLength integer
      required

      Optional hash length used to hash password.

    • name string

      User name. Max length: 128 chars.

  • Response
    • 201 application/json
Endpoint
POST /users/scrypt
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.createScryptUser(
    userId = "<USER_ID>",
    email = "email@example.com",
    password = "password",
    passwordSalt = "<PASSWORD_SALT>",
    passwordCpu = 0,
    passwordMemory = 0,
    passwordParallel = 0,
    passwordLength = 0,
    name = "<NAME>" // optional
)

Create user with Scrypt modified password

Create a new user. Password provided must be hashed with the Scrypt Modified algorithm. Use the POST /users endpoint to create users with a plain text password.

  • Request
    • userId string
      required

      User ID. Choose a custom ID or generate a random ID with ID.unique(). Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.

    • email string
      required

      User email.

    • password string
      required

      User password hashed using Scrypt Modified.

    • passwordSalt string
      required

      Salt used to hash password.

    • passwordSaltSeparator string
      required

      Salt separator used to hash password.

    • passwordSignerKey string
      required

      Signer key used to hash password.

    • name string

      User name. Max length: 128 chars.

  • Response
    • 201 application/json
Endpoint
POST /users/scrypt-modified
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.createScryptModifiedUser(
    userId = "<USER_ID>",
    email = "email@example.com",
    password = "password",
    passwordSalt = "<PASSWORD_SALT>",
    passwordSaltSeparator = "<PASSWORD_SALT_SEPARATOR>",
    passwordSignerKey = "<PASSWORD_SIGNER_KEY>",
    name = "<NAME>" // optional
)

Create user with SHA password

Create a new user. Password provided must be hashed with the SHA algorithm. Use the POST /users endpoint to create users with a plain text password.

  • Request
    • userId string
      required

      User ID. Choose a custom ID or generate a random ID with ID.unique(). Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.

    • email string
      required

      User email.

    • password string
      required

      User password hashed using SHA.

    • passwordVersion string

      Optional SHA version used to hash password. Allowed values are: 'sha1', 'sha224', 'sha256', 'sha384', 'sha512/224', 'sha512/256', 'sha512', 'sha3-224', 'sha3-256', 'sha3-384', 'sha3-512'

    • name string

      User name. Max length: 128 chars.

  • Response
    • 201 application/json
Endpoint
POST /users/sha
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.createSHAUser(
    userId = "<USER_ID>",
    email = "email@example.com",
    password = "password",
    passwordVersion = "sha1", // optional
    name = "<NAME>" // optional
)

Get user

Get a user by its unique ID.

  • Request
    • userId string
      required

      User ID.

  • Response
    • 200 application/json
Endpoint
GET /users/{userId}
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.get(
    userId = "<USER_ID>"
)

Delete user

Delete a user by its unique ID, thereby releasing it's ID. Since ID is released and can be reused, all user-related resources like documents or storage files should be deleted before user deletion. If you want to keep ID reserved, use the updateStatus endpoint instead.

  • Request
    • userId string
      required

      User ID.

  • Response
    • 204 application/json
Endpoint
DELETE /users/{userId}
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.delete(
    userId = "<USER_ID>"
)

Update email

Update the user email by its unique ID.

  • Request
    • userId string
      required

      User ID.

    • email string
      required

      User email.

  • Response
    • 200 application/json
Endpoint
PATCH /users/{userId}/email
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.updateEmail(
    userId = "<USER_ID>",
    email = "email@example.com"
)

Create user JWT

Use this endpoint to create a JSON Web Token for user by its unique ID. You can use the resulting JWT to authenticate on behalf of the user. The JWT secret will become invalid if the session it uses gets deleted.

  • Request
    • userId string
      required

      User ID.

    • sessionId string

      Session ID. Use the string 'recent' to use the most recent session. Defaults to the most recent session.

    • duration integer

      Time in seconds before JWT expires. Default duration is 900 seconds, and maximum is 3600 seconds.

  • Response
    • 201 application/json
Endpoint
POST /users/{userId}/jwts
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.createJWT(
    userId = "<USER_ID>",
    sessionId = "<SESSION_ID>", // optional
    duration = 0 // optional
)

Update user labels

Update the user labels by its unique ID.

Labels can be used to grant access to resources. While teams are a way for user's to share access to a resource, labels can be defined by the developer to grant access without an invitation. See the Permissions docs for more info.

  • Request
    • userId string
      required

      User ID.

    • labels array
      required

      Array of user labels. Replaces the previous labels. Maximum of 1000 labels are allowed, each up to 36 alphanumeric characters long.

  • Response
    • 200 application/json
Endpoint
PUT /users/{userId}/labels
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.updateLabels(
    userId = "<USER_ID>",
    labels = listOf()
)

List user logs

Get the user activity logs list by its unique ID.

  • Request
    • userId string
      required

      User ID.

    • queries array

      Array of query strings generated using the Query class provided by the SDK. Learn more about queries. Only supported methods are limit and offset

  • Response
Endpoint
GET /users/{userId}/logs
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.listLogs(
    userId = "<USER_ID>",
    queries = listOf() // optional
)

List user memberships

Get the user membership list by its unique ID.

  • Request
    • userId string
      required

      User ID.

  • Response
Endpoint
GET /users/{userId}/memberships
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.listMemberships(
    userId = "<USER_ID>"
)

Update MFA

Enable or disable MFA on a user account.

  • Request
    • userId string
      required

      User ID.

    • mfa boolean
      required

      Enable or disable MFA.

  • Response
    • 200 application/json
Endpoint
PATCH /users/{userId}/mfa
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.updateMfa(
    userId = "<USER_ID>",
    mfa = false
)

Delete authenticator

Delete an authenticator app.

  • Request
    • userId string
      required

      User ID.

    • type string
      required

      Type of authenticator.

  • Response
    • 200 application/json
Endpoint
DELETE /users/{userId}/mfa/authenticators/{type}
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users
import io.appwrite.enums.AuthenticatorType

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.deleteMfaAuthenticator(
    userId = "<USER_ID>",
    type =  AuthenticatorType.TOTP
)

List factors

List the factors available on the account to be used as a MFA challange.

  • Request
    • userId string
      required

      User ID.

  • Response
Endpoint
GET /users/{userId}/mfa/factors
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.listMfaFactors(
    userId = "<USER_ID>"
)

Get MFA recovery codes

Get recovery codes that can be used as backup for MFA flow by User ID. Before getting codes, they must be generated using createMfaRecoveryCodes method.

Endpoint
GET /users/{userId}/mfa/recovery-codes
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.getMfaRecoveryCodes(
    userId = "<USER_ID>"
)

Regenerate MFA recovery codes

Regenerate recovery codes that can be used as backup for MFA flow by User ID. Before regenerating codes, they must be first generated using createMfaRecoveryCodes method.

Endpoint
PUT /users/{userId}/mfa/recovery-codes
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.updateMfaRecoveryCodes(
    userId = "<USER_ID>"
)

Create MFA recovery codes

Generate recovery codes used as backup for MFA flow for User ID. Recovery codes can be used as a MFA verification type in createMfaChallenge method by client SDK.

Endpoint
PATCH /users/{userId}/mfa/recovery-codes
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.createMfaRecoveryCodes(
    userId = "<USER_ID>"
)

Update name

Update the user name by its unique ID.

  • Request
    • userId string
      required

      User ID.

    • name string
      required

      User name. Max length: 128 chars.

  • Response
    • 200 application/json
Endpoint
PATCH /users/{userId}/name
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.updateName(
    userId = "<USER_ID>",
    name = "<NAME>"
)

Update password

Update the user password by its unique ID.

  • Request
    • userId string
      required

      User ID.

    • password string
      required

      New user password. Must be at least 8 chars.

  • Response
    • 200 application/json
Endpoint
PATCH /users/{userId}/password
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.updatePassword(
    userId = "<USER_ID>",
    password = ""
)

Update phone

Update the user phone by its unique ID.

  • Request
    • userId string
      required

      User ID.

    • number string
      required

      User phone number.

  • Response
    • 200 application/json
Endpoint
PATCH /users/{userId}/phone
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.updatePhone(
    userId = "<USER_ID>",
    number = "+12065550100"
)

Get user preferences

Get the user preferences by its unique ID.

  • Request
    • userId string
      required

      User ID.

  • Response
Endpoint
GET /users/{userId}/prefs
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.getPrefs(
    userId = "<USER_ID>"
)

Update user preferences

Update the user preferences by its unique ID. The object you pass is stored as is, and replaces any previous value. The maximum allowed prefs size is 64kB and throws error if exceeded.

  • Request
    • userId string
      required

      User ID.

    • prefs object
      required

      Prefs key-value JSON object.

  • Response
Endpoint
PATCH /users/{userId}/prefs
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.updatePrefs(
    userId = "<USER_ID>",
    prefs = mapOf( "a" to "b" )
)

List user sessions

Get the user sessions list by its unique ID.

  • Request
    • userId string
      required

      User ID.

  • Response
Endpoint
GET /users/{userId}/sessions
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.listSessions(
    userId = "<USER_ID>"
)

Create session

Creates a session for a user. Returns an immediately usable session object.

If you want to generate a token for a custom authentication flow, use the POST /users/{userId}/tokens endpoint.

  • Request
    • userId string
      required

      User ID. Choose a custom ID or generate a random ID with ID.unique(). Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.

  • Response
Endpoint
POST /users/{userId}/sessions
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.createSession(
    userId = "<USER_ID>"
)

Delete user sessions

Delete all user's sessions by using the user's unique ID.

  • Request
    • userId string
      required

      User ID.

  • Response
    • 204 application/json
Endpoint
DELETE /users/{userId}/sessions
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.deleteSessions(
    userId = "<USER_ID>"
)

Delete user session

Delete a user sessions by its unique ID.

  • Request
    • userId string
      required

      User ID.

    • sessionId string
      required

      Session ID.

  • Response
    • 204 application/json
Endpoint
DELETE /users/{userId}/sessions/{sessionId}
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.deleteSession(
    userId = "<USER_ID>",
    sessionId = "<SESSION_ID>"
)

Update user status

Update the user status by its unique ID. Use this endpoint as an alternative to deleting a user if you want to keep user's ID reserved.

  • Request
    • userId string
      required

      User ID.

    • status boolean
      required

      User Status. To activate the user pass true and to block the user pass false.

  • Response
    • 200 application/json
Endpoint
PATCH /users/{userId}/status
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.updateStatus(
    userId = "<USER_ID>",
    status = false
)

List user targets

List the messaging targets that are associated with a user.

  • Request
    • userId string
      required

      User ID.

    • queries array

      Array of query strings generated using the Query class provided by the SDK. Learn more about queries. Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: name, email, phone, status, passwordUpdate, registration, emailVerification, phoneVerification, labels

  • Response
Endpoint
GET /users/{userId}/targets
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.listTargets(
    userId = "<USER_ID>",
    queries = listOf() // optional
)

Create user target

Create a messaging target.

  • Request
    • userId string
      required

      User ID.

    • targetId string
      required

      Target ID. Choose a custom ID or generate a random ID with ID.unique(). Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.

    • providerType string
      required

      The target provider type. Can be one of the following: email, sms or push.

    • identifier string
      required

      The target identifier (token, email, phone etc.)

    • providerId string

      Provider ID. Message will be sent to this target from the specified provider ID. If no provider ID is set the first setup provider will be used.

    • name string

      Target name. Max length: 128 chars. For example: My Awesome App Galaxy S23.

  • Response
Endpoint
POST /users/{userId}/targets
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users
import io.appwrite.enums.MessagingProviderType

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.createTarget(
    userId = "<USER_ID>",
    targetId = "<TARGET_ID>",
    providerType =  MessagingProviderType.EMAIL,
    identifier = "<IDENTIFIER>",
    providerId = "<PROVIDER_ID>", // optional
    name = "<NAME>" // optional
)

Get user target

Get a user's push notification target by ID.

  • Request
    • userId string
      required

      User ID.

    • targetId string
      required

      Target ID.

  • Response
Endpoint
GET /users/{userId}/targets/{targetId}
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.getTarget(
    userId = "<USER_ID>",
    targetId = "<TARGET_ID>"
)

Update user target

Update a messaging target.

  • Request
    • userId string
      required

      User ID.

    • targetId string
      required

      Target ID.

    • identifier string

      The target identifier (token, email, phone etc.)

    • providerId string

      Provider ID. Message will be sent to this target from the specified provider ID. If no provider ID is set the first setup provider will be used.

    • name string

      Target name. Max length: 128 chars. For example: My Awesome App Galaxy S23.

  • Response
Endpoint
PATCH /users/{userId}/targets/{targetId}
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.updateTarget(
    userId = "<USER_ID>",
    targetId = "<TARGET_ID>",
    identifier = "<IDENTIFIER>", // optional
    providerId = "<PROVIDER_ID>", // optional
    name = "<NAME>" // optional
)

Delete user target

Delete a messaging target.

  • Request
    • userId string
      required

      User ID.

    • targetId string
      required

      Target ID.

  • Response
    • 204 application/json
Endpoint
DELETE /users/{userId}/targets/{targetId}
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.deleteTarget(
    userId = "<USER_ID>",
    targetId = "<TARGET_ID>"
)

Create token

Returns a token with a secret key for creating a session. Use the user ID and secret and submit a request to the PUT /account/sessions/token endpoint to complete the login process.

  • Request
    • userId string
      required

      User ID.

    • length integer

      Token length in characters. The default length is 6 characters

    • expire integer

      Token expiration period in seconds. The default expiration is 15 minutes.

  • Response
    • 201 application/json
Endpoint
POST /users/{userId}/tokens
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.createToken(
    userId = "<USER_ID>",
    length = 4, // optional
    expire = 60 // optional
)

Update email verification

Update the user email verification status by its unique ID.

  • Request
    • userId string
      required

      User ID.

    • emailVerification boolean
      required

      User email verification status.

  • Response
    • 200 application/json
Endpoint
PATCH /users/{userId}/verification
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.updateEmailVerification(
    userId = "<USER_ID>",
    emailVerification = false
)

Update phone verification

Update the user phone verification status by its unique ID.

  • Request
    • userId string
      required

      User ID.

    • phoneVerification boolean
      required

      User phone verification status.

  • Response
    • 200 application/json
Endpoint
PATCH /users/{userId}/verification/phone
Kotlin
import io.appwrite.Client
import io.appwrite.coroutines.CoroutineCallback
import io.appwrite.services.Users

val client = Client()
    .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID
    .setKey("<YOUR_API_KEY>") // Your secret API key

val users = Users(client)

val response = users.updatePhoneVerification(
    userId = "<USER_ID>",
    phoneVerification = false
)
Copyright © 2024 Appwrite