Permissions

Appwrite's permission mechanism offers a simple, yet flexible way to manage which users, teams, or roles can access a specific resource in your project, such as documents and files.

Using permissions, you can decide that only user A and user B will have read and update access to a specific database document, while user C and team X will be the only ones with delete access.

As the name suggests, read permission allows a user to read a resource, create allows users to create new resources, update allows a user to make changes to a resource, and delete allows the user to remove the resource.

All permissions can be granted to individuals or groups of users, entire teams, or only to team members with a specific role. Permission can also be granted based on authentication status, such as to all users, only authenticated users, or only guest users.

A project user can only grant permissions to a resource that they have. For example, if a user is trying to share a document with a team that they are not a member of, they will encounter a 401 not authorized error. If your app needs users to grant access to teams they're not a member of, you can create Appwrite Functions with a Server SDK to achieve this functionality.

Appwrite resource

An Appwrite resource can be a database, collection, document, bucket, or file. Each resource has its own set of permissions to define who can interact with it.

Using the Appwrite permissions mechanism, you can grant resource access to users, teams, and members with different roles.

Default values

If you create a resource using a Server SDK or the Appwrite Console without explicit permissions, no one can access it by default because the permissions will be empty. If you create a resource using a Client SDK without explicit permissions, the creator will be granted read, update, and delete permissions on that resource by default.

Server integration

Server integrations can be used for increased flexibility. When using a Server SDK in combination with the proper API key scopes, you can have any type of access to any of your project resources regardless of their permissions.

Using the server integration flexibility, you can change resource permissions, share resources between different users and teams, or edit and delete them without any limitations.

Permission types

In Client and Server SDKs, you will find a Permission class with helper methods for each role described below:

Permission roles

In Client and Server SDKs, you will find a Role class with helper methods for each role described below:

Examples

The examples below will show you how you can use the different Appwrite permissions to manage access control to your project resources.

The following examples are using the Appwrite Web SDK but can be applied similarly to any of the other Appwrite SDKs.

Example 1 - Basic usage

In the following example, we are creating a document that can be read by anyone, edited by writers or admins, and deleted by administrators or a user with the user ID user:5c1f88b42259e.

import { Client, Databases, Permission, Role } from "appwrite";

const client = new Client()
    .setEndpoint('https://cloud.appwrite.io/v1')
    .setProject('<PROJECT_ID>');

const databases = new Databases(client);

let promise = databases.createDocument(
    '<DATABASE_ID>',
    '<COLLECTION_ID>',
    {'actorName': 'Chris Evans', 'height': 183},
    [
        Permission.read(Role.any()),                  // Anyone can view this document
        Permission.update(Role.team("writers")),      // Writers can update this document
        Permission.update(Role.team("admin")),        // Admins can update this document
        Permission.delete(Role.user("5c1f88b42259e")), // User 5c1f88b42259e can delete this document
        Permission.delete(Role.team("admin"))          // Admins can delete this document
    ]
);

promise.then(function (response) {
    console.log(response);
}, function (error) {
    console.log(error);
});

Example 2 - Team roles

In the following example, we are creating a document that can be read by members of the team with ID 5c1f88b87435e and can only be edited or deleted by members of the same team that possess the team role owner.

import { Client, Databases, Permission, Role } from "appwrite";

const client = new Client()
    .setEndpoint('https://cloud.appwrite.io/v1')
    .setProject('<PROJECT_ID>');

const databases = new Databases(client);

let promise = databases.createDocument(
    '<DATABASE_ID>',
    '<COLLECTION_ID>',
    {'actorName': 'Chris Evans', 'height': 183},
    [
        Permission.read(Role.team("5c1f88b87435e")),             // Only users of team 5c1f88b87435e can read the document
        Permission.update(Role.team("5c1f88b87435e", "owner")), // Only users of team 5c1f88b87435e with the role owner can update the document
        Permission.delete(Role.team("5c1f88b87435e", "owner"))  // Only users of team 5c1f88b87435e with the role owner can delete the document
    ]
);

promise.then(function (response) {
    console.log(response);
}, function (error) {
    console.log(error);
});