View Source Appwrite.Services.Accounts (appwrite v0.1.5)
The Account service allows you to authenticate and manage a user account. You can use the account service to update user information, retrieve the user sessions across different devices, and fetch the user security logs with his or her recent activity. You can authenticate the user account by using multiple sign-in methods available. Once the user is authenticated, a new session object will be created to allow the user to access his or her private data and settings.
Status: In Testing
Summary
Functions
Create a new account.
Creates an anonymous session.
Creates an email-password session.
Creates an email token for user authentication.
Create a JWT for the current user.
Creates a magic URL token for user authentication.
Create a new MFA authenticator.
Create an MFA challenge.
Generate recovery codes for MFA.
Create an OAuth2 session.
Create OAuth2 token.
Creates a phone token for user authentication.
Create phone verification.
Creates a push target.
Create a password recovery request for the user.
Create session.
Create email verification.
Delete an identity by its unique ID.
Delete an MFA authenticator.
Deletes a push target.
Deletes a session by session ID.
Delete all active sessions for the currently logged-in user.
Get the currently logged-in user.
Get recovery codes that can be used as a backup for the MFA flow.
Get the preferences of the currently logged-in user.
Retrieves a session by session ID.
List identities for the currently logged-in user.
List logs for the currently logged-in user.
List the factors available on the account to be used for MFA challenge.
List all active sessions for the currently logged-in user.
Update the email address of the currently logged-in user.
Update magic URL session.
Update MFA status for the account.
Verify an MFA authenticator.
Complete the MFA challenge by providing the one-time password (OTP).
To begin the MFA flow, use create_mfa_challenge/1
.
Regenerate recovery codes for MFA. An OTP challenge is required.
Update the currently logged-in user's name.
Update the currently logged-in user's password.
Update the currently logged-in user's phone number.
Update phone session.
Update phone verification.
Update the preferences of the currently logged-in user.
Updates a push target.
Updates a session to extend its length.
Updates the status of the currently logged-in user.
Update email verification.
Functions
Create a new account.
Parameters
client
: The Appwrite client.user_id
: The unique ID for the new user.email
: The email address of the user.password
: The user's password.name
: (Optional) The user's name.
Returns
{:ok, User.t()}
on success{:error, reason}
on failure
@spec create_anonymous_session(Appwrite.Helpers.Client.t()) :: {:ok, Appwrite.Types.Session.t()} | {:error, any()}
Creates an anonymous session.
Registers an anonymous account in your project and creates a new session for the user.
Returns
{:ok, %Session{}}
on success{:error, reason}
on failure
@spec create_email_password_session( Appwrite.Helpers.Client.t(), String.t() | nil, String.t() | nil ) :: {:ok, Appwrite.Types.Session.t()} | {:error, any()}
Creates an email-password session.
Allows the user to log in with an email and password combination.
Parameters
client
: The Appwrite client.email
: The user's email (required).password
: The user's password (required).
Returns
{:ok, %Session{}}
on success{:error, reason}
on failure
@spec create_email_token( Appwrite.Helpers.Client.t(), String.t(), String.t(), boolean() | nil ) :: {:ok, map()} | {:error, Exception.t()}
Creates an email token for user authentication.
Sends the user an email with a secret key for creating a session.
Parameters
user_id
(required): The user ID.email
(required): The email address.phrase
: Optional phrase for authentication.
Returns
{:ok, token}
on success.{:error, %Appwrite.Exception{}}
on failure.
@spec create_jwt(Appwrite.Helpers.Client.t()) :: {:ok, Appwrite.Types.Jwt.t()} | {:error, any()}
Create a JWT for the current user.
Returns
{:ok, Jwt.t()}
on success{:error, reason}
on failure
create_magic_url_token(client, user_id, email, url \\ nil, phrase \\ nil)
View Source@spec create_magic_url_token( Appwrite.Helpers.Client.t(), String.t(), String.t(), String.t() | nil, boolean() | nil ) :: {:ok, map()} | {:error, Exception.t()}
Creates a magic URL token for user authentication.
Sends the user an email with a magic link for logging in.
Parameters
user_id
(required): The user ID.email
(required): The email address.url
: Optional redirect URL.phrase
: Optional phrase for authentication.
Returns
{:ok, token}
on success.{:error, %Appwrite.Exception{}}
on failure.
@spec create_mfa_authenticator(Appwrite.Helpers.Client.t(), String.t()) :: {:ok, Appwrite.Types.MfaType.t()} | {:error, any()}
Create a new MFA authenticator.
Parameters
client
: The Appwrite client.type
: The type of authenticator.
Returns
{:ok, MfaType.t()}
on success{:error, reason}
on failure
@spec create_mfa_challenge( Appwrite.Helpers.Client.t(), Appwrite.Consts.AuthenticationFactor ) :: {:ok, Appwrite.Types.MfaChallenge.t()} | {:error, any()}
Create an MFA challenge.
Parameters
client
: The Appwrite client.factor
: The MFA factor to challenge.
Returns
{:ok, MfaChallenge.t()}
on success{:error, reason}
on failure
@spec create_mfa_recovery_codes(Appwrite.Helpers.Client.t()) :: Appwrite.Types.MfaRecoveryCodes.t() | {:error, any()}
Generate recovery codes for MFA.
Returns
%MfaRecoveryCodes{}
on success.{:error, reason}
on failure.
create_oauth2_session(client, provider, success \\ nil, failure \\ nil, scopes \\ nil)
View Source@spec create_oauth2_session( Appwrite.Helpers.Client.t(), String.t(), String.t() | nil, String.t() | nil, [String.t()] | nil ) :: {:ok, String.t()} | {:error, any()}
Create an OAuth2 session.
Logs the user in with an OAuth2 provider.
Parameters
client
: The Appwrite client.provider
: The OAuth2 provider.success
: URL to redirect on success.failure
: URL to redirect on failure.scopes
: List of requested OAuth2 scopes.
Returns
{:ok, String.t()}
containing the OAuth2 URL on success{:error, reason}
on failure
create_oauth2_token(client, provider, success \\ nil, failure \\ nil, scopes \\ nil)
View SourceCreate OAuth2 token.
Allow the user to login to their account using the OAuth2 provider of their choice. Each OAuth2 provider should be enabled from the Appwrite console first. Use the success
and failure
arguments to provide redirect URLs back to your app when login is completed.
If authentication succeeds, userId
and secret
of a token will be appended to the success URL as query parameters. These can be used to create a new session using the create_session/3
function.
A user is limited to 10 active sessions at a time by default. Learn more about session limits.
Parameters
client
: Appwrite client.provider
: OAuth2 provider (required).success
: Success redirect URL (optional).failure
: Failure redirect URL (optional).scopes
: OAuth2 scopes (optional).
Returns
{:ok, url}
: Redirect URL.{:error, Exception.t()}
: Error details.
@spec create_phone_token(Appwrite.Helpers.Client.t(), String.t(), String.t()) :: {:ok, map()} | {:error, Exception.t()}
Creates a phone token for user authentication.
Sends the user an SMS with a secret key for creating a session.
Parameters
user_id
(required): The user ID.phone
(required): The phone number.
Returns
{:ok, token}
on success.{:error, %Appwrite.Exception{}}
on failure.
@spec create_phone_verification(Appwrite.Helpers.Client.t()) :: {:ok, Appwrite.Types.Token.t()} | {:error, any()}
Create phone verification.
Use this endpoint to send a verification SMS to the currently logged-in user.
Parameters
client
: Appwrite client.
Returns
{:ok, map()}
: Verification token.{:error, Exception.t()}
: Error details.
create_push_target(client, target_id, identifier, provider_id \\ nil)
View Source@spec create_push_target( Appwrite.Helpers.Client.t(), String.t(), String.t(), String.t() | nil ) :: {:ok, map()} | {:error, Exception.t()}
Creates a push target.
Parameters
target_id
(required): Target identifier.identifier
(required): Unique identifier for the push target.provider_id
: Optional provider ID.
Returns
{:ok, target}
on success.{:error, %Appwrite.Exception{}}
on failure.
@spec create_recovery(Appwrite.Helpers.Client.t(), String.t(), String.t()) :: {:ok, Appwrite.Types.Token.t()} | {:error, any()}
Create a password recovery request for the user.
Parameters
client
(required): The Appwrite client instance.email
(required): The user's email address.url
(required): The URL to redirect the user to after password reset.
Returns
%Token{}
on success.{:error, reason}
on failure.
@spec create_session(Appwrite.Helpers.Client.t(), String.t(), String.t()) :: {:ok, Appwrite.Types.Session.t()} | {:error, any()}
Create session.
Creates a session using the user ID and secret from a token-based authentication flow.
Parameters
client
: The Appwrite client.user_id
: The user ID.secret
: The secret token.
Returns
{:ok, %Session{}}
on success{:error, reason}
on failure
@spec create_verification(Appwrite.Helpers.Client.t(), String.t()) :: {:ok, Appwrite.Types.Token.t()} | {:error, any()}
Create email verification.
Use this endpoint to send a verification message to your user's email address to confirm ownership. Learn more about how to complete the verification process by verifying both the userId
and secret
parameters.
Parameters
client
: Appwrite client.url
: The redirect URL (required).
Returns
{:ok, map()}
: Verification token.{:error, Exception.t()}
: Error details.
@spec delete_identity(Appwrite.Helpers.Client.t(), String.t()) :: {:ok, map()} | {:error, any()}
Delete an identity by its unique ID.
Parameters
client
: The Appwrite client.identity_id
: The ID of the identity to delete.
Returns
{:ok, map()}
on success{:error, reason}
on failure
@spec delete_mfa_authenticator(Appwrite.Helpers.Client.t(), String.t()) :: {:ok, map()} | {:error, any()}
Delete an MFA authenticator.
Parameters
client
: The Appwrite client.type
: The type of authenticator to delete.
Returns
{:ok, map()}
on success{:error, reason}
on failure
@spec delete_push_target(Appwrite.Helpers.Client.t(), String.t()) :: {:ok, map()} | {:error, Exception.t()}
Deletes a push target.
Parameters
target_id
(required): Target identifier.
Returns
{:ok, %{}}
on success.{:error, %Appwrite.Exception{}}
on failure.
@spec delete_session(Appwrite.Helpers.Client.t(), String.t() | nil) :: {:ok, map()} | {:error, any()}
Deletes a session by session ID.
Parameters
client
: The Appwrite client.session_id
: The session ID (use "current" for the current session).
Returns
{:ok, %{}}
on success{:error, reason}
on failure
@spec delete_sessions(Appwrite.Helpers.Client.t()) :: :ok | {:error, any()}
Delete all active sessions for the currently logged-in user.
Returns
:ok
on success.{:error, reason}
on failure.
@spec get(Appwrite.Helpers.Client.t()) :: {:ok, Appwrite.Types.User.t()} | {:error, any()}
Get the currently logged-in user.
Returns
{:ok, User.t()}
on success{:error, reason}
on failure
@spec get_mfa_recovery_codes(Appwrite.Helpers.Client.t()) :: Appwrite.Types.MfaRecoveryCodes.t() | {:error, any()}
Get recovery codes that can be used as a backup for the MFA flow.
Returns
%MfaRecoveryCodes{}
on success.{:error, reason}
on failure.
@spec get_prefs(Appwrite.Helpers.Client.t()) :: {:ok, Appwrite.Types.Preferences.t()} | {:error, any()}
Get the preferences of the currently logged-in user.
Returns
%Preferences{}
on success.{:error, reason}
on failure.
@spec get_session(Appwrite.Helpers.Client.t(), String.t() | nil) :: {:ok, Appwrite.Types.Session.t()} | {:error, any()}
Retrieves a session by session ID.
Parameters
client
: The Appwrite client.session_id
: The session ID (use "current" for the current session).
Returns
{:ok, %Session{}}
on success{:error, reason}
on failure
@spec list_identities(Appwrite.Helpers.Client.t(), [String.t()] | nil) :: {:ok, Appwrite.Types.IdentityList.t()} | {:error, any()}
List identities for the currently logged-in user.
Parameters
client
: The Appwrite client.queries
: (Optional) A list of query strings.
Returns
{:ok, IdentityList.t()}
on success{:error, reason}
on failure
@spec list_logs(Appwrite.Helpers.Client.t(), [String.t()] | nil) :: {:ok, Appwrite.Types.LogList.t()} | {:error, any()}
List logs for the currently logged-in user.
Parameters
client
: The Appwrite client.queries
: (Optional) A list of query strings.
Returns
{:ok, LogList.t()}
on success{:error, reason}
on failure
@spec list_mfa_factors(Appwrite.Helpers.Client.t()) :: Appwrite.Types.MfaFactors.t() | {:error, any()}
List the factors available on the account to be used for MFA challenge.
Returns
%MfaFactors{}
on success.{:error, reason}
on failure.
@spec list_sessions(Appwrite.Helpers.Client.t()) :: {:ok, Appwrite.Types.SessionList.t()} | {:error, any()}
List all active sessions for the currently logged-in user.
Returns
%SessionList{}
on success.{:error, reason}
on failure.
@spec update_email(Appwrite.Helpers.Client.t(), String.t(), String.t()) :: {:ok, Appwrite.Types.User.t()} | {:error, any()}
Update the email address of the currently logged-in user.
Parameters
client
: The Appwrite client.email
: The new email address.password
: The user's password.
Returns
{:ok, User.t()}
on success{:error, reason}
on failure
@spec update_magic_url_session(Appwrite.Helpers.Client.t(), String.t(), String.t()) :: {:ok, Appwrite.Types.Session.t()} | {:error, any()}
Update magic URL session.
Creates a session using the user ID and secret from a token-based authentication flow.
Parameters
client
: The Appwrite client.user_id
: The user ID.secret
: The secret token.
Returns
{:ok, %Session{}}
on success{:error, reason}
on failure
@spec update_mfa(Appwrite.Helpers.Client.t(), boolean()) :: {:ok, Appwrite.Types.User.t()} | {:error, any()}
Update MFA status for the account.
Parameters
client
: The Appwrite client.mfa
: Boolean to enable or disable MFA.
Returns
{:ok, User.t()}
on success{:error, reason}
on failure
@spec update_mfa_authenticator(Appwrite.Helpers.Client.t(), String.t(), String.t()) :: {:ok, Appwrite.Types.User.t()} | {:error, any()}
Verify an MFA authenticator.
Parameters
client
: The Appwrite client.type
: The type of authenticator.otp
: The one-time password to verify.
Returns
{:ok, User.t()}
on success{:error, reason}
on failure
@spec update_mfa_challenge(Appwrite.Helpers.Client.t(), String.t(), String.t()) :: :ok | {:error, any()}
Complete the MFA challenge by providing the one-time password (OTP).
To begin the MFA flow, use create_mfa_challenge/1
.
Parameters
client
(required): The Appwrite client instance.challenge_id
(required): The ID of the challenge.otp
(required): The one-time password.
Returns
:ok
on success.{:error, reason}
on failure.
Examples
iex> update_mfa_challenge(client, "challenge123", "123456")
:ok
@spec update_mfa_recovery_codes(Appwrite.Helpers.Client.t()) :: Appwrite.Types.MfaRecoveryCodes.t() | {:error, any()}
Regenerate recovery codes for MFA. An OTP challenge is required.
Returns
%MfaRecoveryCodes{}
on success.{:error, reason}
on failure.
@spec update_name(Appwrite.Helpers.Client.t(), String.t()) :: {:ok, Appwrite.Types.User.t()} | {:error, any()}
Update the currently logged-in user's name.
Parameters
client
(required): The Appwrite client instance.name
(required): The new name of the user.
Returns
%User{}
on success.{:error, reason}
on failure.
@spec update_password(Appwrite.Helpers.Client.t(), String.t(), String.t() | nil) :: {:ok, Appwrite.Types.User.t()} | {:error, any()}
Update the currently logged-in user's password.
Parameters
client
(required): The Appwrite client instance.password
(required): The new password for the user.old_password
(optional): The user's current password.
Returns
%User{}
on success.{:error, reason}
on failure.
@spec update_phone(Appwrite.Helpers.Client.t(), String.t(), String.t()) :: {:ok, Appwrite.Types.User.t()} | {:error, any()}
Update the currently logged-in user's phone number.
Parameters
client
(required): The Appwrite client instance.phone
(required): The new phone number.password
(required): The user's password.
Returns
%User{}
on success.{:error, reason}
on failure.
@spec update_phone_session(Appwrite.Helpers.Client.t(), String.t(), String.t()) :: {:ok, Appwrite.Types.Session.t()} | {:error, any()}
Update phone session.
Creates a session using the user ID and secret from a phone-based authentication flow.
Parameters
client
: The Appwrite client.user_id
: The user ID.secret
: The secret token.
Returns
{:ok, %Session{}}
on success{:error, reason}
on failure
@spec update_phone_verification(Appwrite.Helpers.Client.t(), String.t(), String.t()) :: {:ok, Appwrite.Types.Token.t()} | {:error, any()}
Update phone verification.
Use this endpoint to complete the user phone verification process.
Parameters
client
: Appwrite client.user_id
: The user's ID (required).secret
: The secret key (required).
Returns
{:ok, map()}
: Verification token.{:error, Exception.t()}
: Error details.
@spec update_prefs(Appwrite.Helpers.Client.t(), map()) :: {:ok, Appwrite.Types.User.t()} | {:error, any()}
Update the preferences of the currently logged-in user.
Parameters
client
(required): The Appwrite client instance.prefs
(required): A map of user preferences.
Returns
%User{}
on success.{:error, reason}
on failure.
@spec update_push_target(Appwrite.Helpers.Client.t(), String.t(), String.t()) :: {:ok, map()} | {:error, Exception.t()}
Updates a push target.
Parameters
target_id
(required): Target identifier.identifier
(required): Unique identifier for the push target.
Returns
{:ok, target}
on success.{:error, %Appwrite.Exception{}}
on failure.
@spec update_session(Appwrite.Helpers.Client.t(), String.t()) :: {:ok, Appwrite.Types.Session.t()} | {:error, any()}
Updates a session to extend its length.
This is useful when the session expiry is short. If the session was created using an OAuth provider, this endpoint refreshes the access token from the provider.
Parameters
client
: The Appwrite client.session_id
: The ID of the session to update.
Returns
{:ok, %Session{}}
on success{:error, reason}
on failure
@spec update_status(Appwrite.Helpers.Client.t()) :: {:ok, map()} | {:error, Exception.t()}
Updates the status of the currently logged-in user.
Blocks the user account permanently. The user record is not deleted, but the account is blocked from access.
Returns
{:ok, user}
on success.{:error, %Appwrite.Exception{}}
on failure.
@spec update_verification(Appwrite.Helpers.Client.t(), String.t(), String.t()) :: {:ok, Appwrite.Types.Token.t()} | {:error, any()}
Update email verification.
Use this endpoint to complete the user email verification process.
Parameters
client
: Appwrite client.user_id
: The user's ID (required).secret
: The secret key (required).
Returns
{:ok, map()}
: Verification token.{:error, Exception.t()}
: Error details.