Docs

Auth

The authentication service allows you to verify users accounts using basic email and password login or with a supported OAuth provider. The auth service also exposes methods to confirm users email account and recover users forgotten passwords.

You can also learn how to configure support for our supported OAuth providers. You can review our currently available OAuth providers from your project console under the 'users' menu.

Register User

POST/auth/register

Use this endpoint to allow a new user to register an account in your project. Use the success and failure URL's to redirect users back to your application after signup completes.

If registration completes successfully user will be sent with a confirmation email in order to confirm he is the owner of the account email address. Use the redirect parameter to redirect the user from the confirmation email back to your app. When the user is redirected, use the /auth/confirm endpoint to complete the account confirmation.

Please notice that in order to avoid a Redirect Attacks the only valid redirect URL's are the once from domains you have set when added your platforms in the console interface.

When not using the success or failure redirect arguments this endpoint will result with a 200 status code and the user account object on success and with 401 status error on failure. This behavior was applied to help the web clients deal with browsers who don't allow to set 3rd party HTTP cookies needed for saving the account session token.

Arguments

Name Type Description
email required string

Account email

password required string

User password

redirect required string

Confirmation page to redirect user after confirm token has been sent to user email

name optional string

User name

success optional string

Redirect when registration succeed

failure optional string

Redirect when registration failed

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
        setKey('')
    ;
    
    let promise = sdk.auth.register('email@example.com', 'password', 'https://example.com');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });
  • <?php
    
    use Appwrite\Client;
    use Appwrite\Services\Auth;
    
    $client = new Client();
    
    $client
        setProject('')
        setKey('')
    ;
    
    $auth = new Auth($client);
    
    $result = $auth->register('email@example.com', 'password', 'https://example.com');

Confirm User

POST/auth/register/confirm

Use this endpoint to complete the confirmation of the user account email address. Both the userId and token arguments will be passed as query parameters to the redirect URL you have provided when sending your request to the /auth/register endpoint.

Arguments

Name Type Description
userId required string

User unique ID

token required string

Confirmation secret token

Example Request
  • let sdk = new Appwrite();
    
    sdk
    ;
    
    let promise = sdk.auth.confirm('[USER_ID]', '[TOKEN]');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });
  • <?php
    
    use Appwrite\Client;
    use Appwrite\Services\Auth;
    
    $client = new Client();
    
    $client
    ;
    
    $auth = new Auth($client);
    
    $result = $auth->confirm('[USER_ID]', '[TOKEN]');

Resend Confirmation

POST/auth/register/confirm/resend

This endpoint allows the user to request your app to resend him his email confirmation message. The redirect arguments acts the same way as in /auth/register endpoint.

Please notice that in order to avoid a Redirect Attacks the only valid redirect URL's are the once from domains you have set when added your platforms in the console interface.

Arguments

Name Type Description
redirect required string

Confirmation page to redirect user to your app after confirm token has been sent to user email.

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
        setKey('')
    ;
    
    let promise = sdk.auth.confirmResend('https://example.com');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });
  • <?php
    
    use Appwrite\Client;
    use Appwrite\Services\Auth;
    
    $client = new Client();
    
    $client
        setProject('')
        setKey('')
    ;
    
    $auth = new Auth($client);
    
    $result = $auth->confirmResend('https://example.com');

Login User

POST/auth/login

Allow the user to login into his account by providing a valid email and password combination. Use the success and failure arguments to provide a redirect URL\'s back to your app when login is completed.

Please notice that in order to avoid a Redirect Attacks the only valid redirect URL's are the once from domains you have set when added your platforms in the console interface.

When not using the success or failure redirect arguments this endpoint will result with a 200 status code and the user account object on success and with 401 status error on failure. This behavior was applied to help the web clients deal with browsers who don't allow to set 3rd party HTTP cookies needed for saving the account session token.

Arguments

Name Type Description
email required string

User account email address

password required string

User account password

success optional string

URL to redirect back to your app after a successful login attempt.

failure optional string

URL to redirect back to your app after a failed login attempt.

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
        setKey('')
    ;
    
    let promise = sdk.auth.login('email@example.com', 'password');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });
  • <?php
    
    use Appwrite\Client;
    use Appwrite\Services\Auth;
    
    $client = new Client();
    
    $client
        setProject('')
        setKey('')
    ;
    
    $auth = new Auth($client);
    
    $result = $auth->login('email@example.com', 'password');

Logout Current Session

DELETE/auth/logout

Use this endpoint to log out the currently logged in user from his account. When succeed this endpoint will delete the user session and remove the session secret cookie.

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
        setKey('')
    ;
    
    let promise = sdk.auth.logout();
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });
  • <?php
    
    use Appwrite\Client;
    use Appwrite\Services\Auth;
    
    $client = new Client();
    
    $client
        setProject('')
        setKey('')
    ;
    
    $auth = new Auth($client);
    
    $result = $auth->logout();

Logout Specific Session

DELETE/auth/logout/{id}

Use this endpoint to log out the currently logged in user from all his account sessions across all his different devices. When using the option id argument, only the session unique ID provider will be deleted.

Arguments

Name Type Description
id required string

User specific session unique ID number. if 0 delete all sessions.

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
        setKey('')
    ;
    
    let promise = sdk.auth.logoutBySession('[USER_ID]');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });
  • <?php
    
    use Appwrite\Client;
    use Appwrite\Services\Auth;
    
    $client = new Client();
    
    $client
        setProject('')
        setKey('')
    ;
    
    $auth = new Auth($client);
    
    $result = $auth->logoutBySession('[USER_ID]');

Password Recovery

POST/auth/recovery

Sends the user an email with a temporary secret token for password reset. When the user clicks the confirmation link he is redirected back to your app password reset redirect URL with a secret token and email address values attached to the URL query string. Use the query string params to submit a request to the /auth/password/reset endpoint to complete the process.

Arguments

Name Type Description
email required string

User account email address.

redirect required string

Reset page in your app to redirect user after reset token has been sent to user email.

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
        setKey('')
    ;
    
    let promise = sdk.auth.recovery('email@example.com', 'https://example.com');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });
  • <?php
    
    use Appwrite\Client;
    use Appwrite\Services\Auth;
    
    $client = new Client();
    
    $client
        setProject('')
        setKey('')
    ;
    
    $auth = new Auth($client);
    
    $result = $auth->recovery('email@example.com', 'https://example.com');

Password Reset

PUT/auth/recovery/reset

Use this endpoint to complete the user account password reset. Both the userId and token arguments will be passed as query parameters to the redirect URL you have provided when sending your request to the /auth/recovery endpoint.

Please notice that in order to avoid a Redirect Attacks the only valid redirect URL's are the once from domains you have set when added your platforms in the console interface.

Arguments

Name Type Description
userId required string

User account email address.

token required string

Valid reset token.

password-a required string

New password.

password-b required string

New password again.

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
        setKey('')
    ;
    
    let promise = sdk.auth.recoveryReset('[USER_ID]', '[TOKEN]', 'password', 'password');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });
  • <?php
    
    use Appwrite\Client;
    use Appwrite\Services\Auth;
    
    $client = new Client();
    
    $client
        setProject('')
        setKey('')
    ;
    
    $auth = new Auth($client);
    
    $result = $auth->recoveryReset('[USER_ID]', '[TOKEN]', 'password', 'password');

OAuth Login

GET/oauth/{provider}

Arguments

Name Type Description
provider required string

OAuth Provider

success optional string

URL to redirect back to your app after a successful login attempt.

failure optional string

URL to redirect back to your app after a failed login attempt.

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
        setKey('')
    ;
    
    let promise = sdk.auth.oauth('bitbucket');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });
  • <?php
    
    use Appwrite\Client;
    use Appwrite\Services\Auth;
    
    $client = new Client();
    
    $client
        setProject('')
        setKey('')
    ;
    
    $auth = new Auth($client);
    
    $result = $auth->oauth('bitbucket');

OAuth Callback

GET/oauth/callback/{provider}/{projectId}

Arguments

Name Type Description
projectId required string

Project unique ID

provider required string

OAuth provider

code required string

OAuth code

state optional string

Login state params

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
        setKey('')
    ;
    
    let promise = sdk.auth.oauthCallback('[PROJECT_ID]', 'bitbucket', '[CODE]');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });
  • <?php
    
    use Appwrite\Client;
    use Appwrite\Services\Auth;
    
    $client = new Client();
    
    $client
        setProject('')
        setKey('')
    ;
    
    $auth = new Auth($client);
    
    $result = $auth->oauthCallback('[PROJECT_ID]', 'bitbucket', '[CODE]');