DEV Community

loading...
Cover image for #30DaysOfAppwrite : Accounts & Users API
Appwrite

#30DaysOfAppwrite : Accounts & Users API

christyjacob4 profile image Christy Jacob ・6 min read

Intro

#30DaysOfAppwrite is a month long event focused at giving developers a walkthrough of all of Appwrite's features, starting from the basics to more advanced features like Cloud Functions! Alongside we will also be building a fully featured Medium Clone to demonstrate how these
concepts can be applied when building a real world app. We also have some exciting prizes for developers who follow along with us!

Accounts & Users API

Welcome to Day 8 👋. The Users and Accounts APIs seem to raise questions for newer Appwrite devs on our Discord server. Today, it's time to answer all of them. If you followed us yesterday, we reviewed the differences between the Client and Server Side SDKs and discussed the scopes accessible to each of them. So if you haven't already, we recommend you to read that first for some context.

The Main Difference?

If you're looking for a TLDR; this table should help you.

Users API Accounts API
Server Side API Client Side API
Accessed using an API Key Accessed using a Cookie (or JWT)
Operates in an Admin Scope Operates in the scope of the currently logged in user
Perform CRUD operations on all of your app's users Perform CRUD operations on the currently logged in user

If you're in a quest for more information, read along 😊

The Users API is part of the Server Side SDK specification and operates in an admin scope (i.e using an API key) with access to all your project users. The Users API allows you to perform actions like create, update, delete and list your app's users, create, update and delete their preferences, etc. The complete documentation for the Users API can be found in our docs.

Alternatively, the Accounts API operates in the scope of the currently logged in user (using a cookie or JWT) and usually using a client-side integration. The Accounts API allows you to create an account, create user sessions using username and password as well as OAuth2 , update your accounts' email and password, initiate password recoveries, initiate email verifications, etc. The complete documentation for the Accounts API can be found here.

Deep Dive into the Accounts API

Let's try to understand the Accounts API a little better. Some of the most notable methods of the Accounts API are the createSession() and the createOAuth2Session() methods. If successful, their response contains a set-cookie header which then tells the browser to save and include this cookie with every subsequent request. In our Flutter ( and upcoming Android ) SDKs, we make use of a Cookie Jar / Cookie Store to achieve similar functionality.

Appwrite 0.8 adds support for Anonymous Users 🤩 .When you develop an application, there might be times when you want to let a user interact with parts of your app before they're signed in. This also increases the conversion rate of your users, since the hurdle of registration is very high. If an anonymous user decides to sign up to your app, they can later convert their account using their email and password or the OAuth method.

With 0.8, our Dashboard has been updated as well giving you finer control over the allowed login methods for your project 🤩 !!
Enable login methods

Let's make our first request using the Accounts API. To see this in action in a complete app, check out the source code of our demo apps.

We'll be using a JavaScript example for this tutorial. Whether you're using a framework or vanilla JS, it's really easy to get started - our Getting Started for Web tutorial explains how. Once you have installed and initialised your SDK, you can follow along.

create()

This is the method to use if you want to implement Sign Up functionality in your app. Do note that this will only create a new user. You will still need to call the createSession() method using the same email and password to actually create a new session for this user.

let promise = sdk.account.create("email@example.com", "password", "name");

promise.then(
  function (response) {
    console.log(response); // Success
  },
  function (error) {
    console.log(error); // Failure
  }
);
Enter fullscreen mode Exit fullscreen mode

createSession()

If you want to achieve Login functionality in your app, this is the method you need. This method creates a session for an existing user. So make sure you have already called create() before this.

// Using the promise syntax
let promise = sdk.account.createSession("email@example.com", "password");
promise.then(
  function (response) {
    console.log(response); // Success
  },
  function (error) {
    console.log(error); // Failure
  }
);

// Or using async/await
const login = async () => {
  try {
    let response = await sdk.account.createSession(
      "email@example.com",
      "password"
    );
    console.log(response);
  } catch (e) {
    console.log(e);
  }
};
login();
Enter fullscreen mode Exit fullscreen mode

If you inspect the response from createSession() you'll find the following headers.

set-cookie:
a_session_6062f9c2c09ce_legacy=eyJpZCI6IjYwNmI3Y....NmVhMzQ2In0=; expires=Wed, 27-Apr-2022 14:17:29 GMT; path=/; domain=.demo.appwrite.io; secure; httponly

set-cookie:
a_session_6062f9c2c09ce=eyJpZCI6IjYwNmI3Y....NmVhMzQ2In0=; expires=Wed, 27-Apr-2022 14:17:29 GMT; path=/; domain=.demo.appwrite.io; secure; httponly; samesite=None

x-fallback-cookies
{"a_session_6062f9c2c09ce":"eyJpZCI6IjYwNmI3Y....NmVhMzQ2In0="}

Enter fullscreen mode Exit fullscreen mode

An Appwrite session cookie uses the following syntax: a_session_<PROJECT-ID>, a_session_<PROJECT-ID>_legacy. Since many browsers disable 3rd party cookies, we use the x-fallback-cookies header to store the cookie in local storage and then use it in subsequent requests if the cookie has not already been set.

deleteSession()

In order to implement Logout functionality, you will need to delete a session using a session ID. You can delete the current session by passing current in place of the SESSION_ID.

let promise = sdk.account.deleteSession("[SESSION_ID]");

promise.then(
  function (response) {
    console.log(response); // Success
  },
  function (error) {
    console.log(error); // Failure
  }
);
Enter fullscreen mode Exit fullscreen mode

We've covered just a few essential methods to convey how the API works. The complete list of functionality can be found here.

Deep Dive into the Users API

We can achieve all the functionality we discussed above with the Users API as well. However, you would be performing all the actions using an API key. If you're following along from yesterday, you would already have a project and API key set up. Otherwise, you can quickly get started here.

create()

The create method can be used to create a new user. Do note that this is not the same as creating a session using the Accounts API. There is no cookie involved here. Think of this as an admin, creating an account on behalf of one of his users. To create a session, the user will have use these credentials to login from a client side app.

let promise = users.create("email@example.com", "password");

promise.then(
  function (response) {
    console.log(response);
  },
  function (error) {
    console.log(error);
  }
);
Enter fullscreen mode Exit fullscreen mode

deleteSession()

Let's say that you have a Cloud Function that monitors account logins and alerts a user about a suspicious login from a different location or IP. In this case, as a preventive measure you might want to delete the session or block the account altogether until the real user takes action. The deleteSession() method comes handy in this case.

let promise = users.deleteSession("[USER_ID]", "[SESSION_ID]");

promise.then(
  function (response) {
    console.log(response);
  },
  function (error) {
    console.log(error);
  }
);
Enter fullscreen mode Exit fullscreen mode

So for some closing remarks, use the Accounts API when building a client side app and the Users API when building a server side app.
In the next blog post, we will use the Accounts API to add some cool functionality to our blog app 🤩.

Credits

We hope you liked this write up. You can follow #30DaysOfAppwrite on Social Media to keep up with all of our posts. The complete event timeline can be found here

Feel free to reach out to us on Discord if you would like to learn more about Appwrite, Aliens or Unicorns 🦄. Stay tuned for tomorrow's article! Until then 👋

Discussion (0)

Forem Open with the Forem app