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 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 confirmation 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 accessing this route using Javascript from the browser, success and failure parameter URLs are required. Appwrite server will respond with a 301 redirect status code and will set the user session cookie. This behavior is enforced because modern browsers are limiting 3rd party cookies in XHR of fetch requests to protect user privacy.

Arguments

Name Type Description
email required string

Account email

password required string

User password

confirmation required string

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

success optional string

Redirect when registration succeed

failure optional string

Redirect when registration failed

name optional string

User name

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
    ;
    
    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');
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new Auth.Client();
    
    let auth = new sdk.Auth(client);
    
    client
        setProject('')
        setKey('')
    ;
    
    let promise = auth.register('email@example.com', 'password', 'https://example.com');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });

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]');
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new Auth.Client();
    
    let auth = new sdk.Auth(client);
    
    client
    ;
    
    let promise = auth.confirm('[USER_ID]', '[TOKEN]');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });

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
confirmation 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('')
    ;
    
    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');
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new Auth.Client();
    
    let auth = new sdk.Auth(client);
    
    client
        setProject('')
        setKey('')
    ;
    
    let promise = auth.confirmResend('https://example.com');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });

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 accessing this route using Javascript from the browser, success and failure parameter URLs are required. Appwrite server will respond with a 301 redirect status code and will set the user session cookie. This behavior is enforced because modern browsers are limiting 3rd party cookies in XHR of fetch requests to protect user privacy.

Arguments

Name Type Description
email required string

User account email address

password required string

User account password

success required string

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

failure required string

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

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
    ;
    
    let promise = sdk.auth.login('email@example.com', 'password', 'https://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->login('email@example.com', 'password', 'https://example.com', 'https://example.com');
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new Auth.Client();
    
    let auth = new sdk.Auth(client);
    
    client
        setProject('')
        setKey('')
    ;
    
    let promise = auth.login('email@example.com', 'password', 'https://example.com', 'https://example.com');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });

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 from the user client.

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
    ;
    
    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();
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new Auth.Client();
    
    let auth = new sdk.Auth(client);
    
    client
        setProject('')
        setKey('')
    ;
    
    let promise = auth.logout();
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });

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('')
    ;
    
    let promise = sdk.auth.logoutBySession('[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('[ID]');
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new Auth.Client();
    
    let auth = new sdk.Auth(client);
    
    client
        setProject('')
        setKey('')
    ;
    
    let promise = auth.logoutBySession('[ID]');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });

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.

confirmation required string

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

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
    ;
    
    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');
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new Auth.Client();
    
    let auth = new sdk.Auth(client);
    
    client
        setProject('')
        setKey('')
    ;
    
    let promise = auth.recovery('email@example.com', 'https://example.com');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });

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('')
    ;
    
    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');
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new Auth.Client();
    
    let auth = new sdk.Auth(client);
    
    client
        setProject('')
        setKey('')
    ;
    
    let promise = auth.recoveryReset('[USER_ID]', '[TOKEN]', 'password', 'password');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });

OAuth Login

GET/auth/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('')
    ;
    
    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');
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new Auth.Client();
    
    let auth = new sdk.Auth(client);
    
    client
        setProject('')
        setKey('')
    ;
    
    let promise = auth.oauth('bitbucket');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });

OAuth Callback

GET/auth/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('')
    ;
    
    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]');
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new Auth.Client();
    
    let auth = new sdk.Auth(client);
    
    client
        setProject('')
        setKey('')
    ;
    
    let promise = auth.oauthCallback('[PROJECT_ID]', 'bitbucket', '[CODE]');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });