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 and enable our currently available OAuth providers from your project console under the 'users -> providers' menu.

Register

POST/auth/register

Use this endpoint to allow a new user to register an account in your project. Use the success and failure URLs 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 Attack the only valid redirect URLs are the ones from domains you have set when adding 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.

Rate Limits

This endpoint is limited to 10 requests in every 60 minutes. We use rate limits to avoid service abuse by users and as a security practice. Learn more about rate limiting.

Arguments

Name Type Description
email required string

Account email

password required string

User password

confirm 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('')
    ;
    
    /**
     * Will redirect to relevant page
     *  depends on the operation result
     */
    sdk.auth.register(
        'email@example.com',
        'password',
        'http://example.com/confirm',
        'http://example.com/success', // required for JS SDK
        'http://example.com/failure' // required for JS SDK
    );
  • <?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 sdk.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);
    });

Confirmation

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.

Rate Limits

This endpoint is limited to 10 requests in every 60 minutes. We use rate limits to avoid service abuse by users and as a security practice. Learn more about rate limiting.

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 sdk.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 act the same way as in /auth/register endpoint.

Please notice that in order to avoid a Redirect Attack the only valid redirect URLs are the ones from domains you have set when adding your platforms in the console interface.

Rate Limits

This endpoint is limited to 10 requests in every 60 minutes. We use rate limits to avoid service abuse by users and as a security practice. Learn more about rate limiting.

Arguments

Name Type Description
confirm required string

Confirmation URL 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 sdk.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

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 Attack the only valid redirect URLs are the ones from domains you have set when adding 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.

Rate Limits

This endpoint is limited to 10 requests in every 60 minutes. We use rate limits to avoid service abuse by users and as a security practice. Learn more about rate limiting.

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('')
    ;
    
    /**
     * Will redirect to relevant page
     *  depends on the operation result
     */
    sdk.auth.login(
        'email@example.com',
        'password',
        'http://example.com/success', // required for JS SDK
        'http://example.com/failure' // required for JS SDK
    );
  • <?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');
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new sdk.Client();
    
    let auth = new sdk.Auth(client);
    
    client
        .setProject('')
        .setKey('')
    ;
    
    let promise = auth.login('email@example.com', 'password');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });

Login with OAuth

GET/auth/login/oauth/{provider}

Allow the user to login to his account using the OAuth provider of his choice. Each OAuth provider should be enabled from the Appwrite console first. Use the success and failure arguments to provide a redirect URL's back to your app when login is completed.

Rate Limits

This endpoint is limited to 50 requests in every 60 minutes. We use rate limits to avoid service abuse by users and as a security practice. Learn more about rate limiting.

Arguments

Name Type Description
provider required string

OAuth Provider. Currently, supported providers are: bitbucket, facebook, github, gitlab, google, microsoft, linkedin, slack, dropbox, amazon, vk

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('')
    ;
    
    /**
     * Will redirect to relevant page
     *  depends on the operation result
     */
    sdk.auth.oauth(
        'facebook',
        'http://example.com/success',
        'http://example.com/failure'
    );
  • <?php
    
    use Appwrite\Client;
    use Appwrite\Services\Auth;
    
    $client = new Client();
    
    $client
        ->setProject('')
        ->setKey('')
    ;
    
    $auth = new Auth($client);
    
    $result = $auth->oauth('bitbucket', 'https://example.com', 'https://example.com');
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new sdk.Client();
    
    let auth = new sdk.Auth(client);
    
    client
        .setProject('')
        .setKey('')
    ;
    
    let promise = auth.oauth('bitbucket', '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 successful this endpoint will delete the user session and remove the session secret cookie from the user client.

Rate Limits

This endpoint is limited to 100 requests in every 60 minutes. We use rate limits to avoid service abuse by users and as a security practice. Learn more about rate limiting.

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 sdk.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.

Rate Limits

This endpoint is limited to 100 requests in every 60 minutes. We use rate limits to avoid service abuse by users and as a security practice. Learn more about rate limiting.

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 sdk.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.

Rate Limits

This endpoint is limited to 10 requests in every 60 minutes. We use rate limits to avoid service abuse by users and as a security practice. Learn more about rate limiting.

Arguments

Name Type Description
email required string

User account email address.

reset required string

Reset URL in your app to redirect the user after the reset token has been sent to the 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 sdk.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 Attack the only valid redirect URLs are the ones from domains you have set when adding your platforms in the console interface.

Rate Limits

This endpoint is limited to 10 requests in every 60 minutes. We use rate limits to avoid service abuse by users and as a security practice. Learn more about rate limiting.

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 sdk.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);
    });