<p>Appwrite permission mechanism offers a simple, yet flexible way to manage which users, teams, or roles can access a specific resource in your project, like documents and files.</p>

<p>Using permissions, you can decide that only <span class="tag">user A</span> and <span class="tag">user B</span> will have read and update access to a specific database document, while <span class="tag">user C</span> and <span class="tag">team X</span> will be the only ones with delete access.</p>

<p>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.</p>

<p>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.</p>

<p>A project user can only grant a resource with permissions that they own. 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 <a href="/docs/getting-started-for-server">Server SDK</a> to achieve this functionality.</p>

<div class="notice calm margin-top-large margin-bottom-large">
    <h4>Appwrite Resource</h4>
    
    <p>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.</p>

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

<h2 id="default-values"><a href="/docs/permissions#default-values">Default Values</a></h2>

<p>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.</p>

<h2 id="server-integration"><a href="/docs/permissions#server-integration">Server Integration</a></h2>

<p>Server integrations can be used for increased flexibility. When using a Server SDK in combination with the proper <a href="/docs/keys#scopes">API key scopes</a>, you can have any type of access to any of your project resources regardless of their permissions.</p>

<p>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.</p>

<h2 id="permission-types"><a href="/docs/permissions#permission-types">Permission Types</a></h2>
<p>In Client and Server SDKs, you will find a <b>Permission</b> class with helper methods for each role described below.</p>
<table class="full text-size-small">
    <thead>
    <tr>
        <td style="width: 200px">Type</td>
        <td>Description</td>
    </tr>
    </thead>
    <tbody>
    <tr>
        <td>Permission.read()</td>
        <td>Access to read a resource.</td>
    </tr>
    <tr>
        <td>Permission.create()</td>
        <td>Access to create new resources. Does not apply to files or documents. Applying this type of access to files or documents results in an error.</td>
    </tr>
    <tr>
        <td>Permission.update()</td>
        <td>Access to change a resource, but not remove or create new resources. Does not apply to functions.</td>
    </tr>
    <tr>
        <td>Permission.delete()</td>
        <td>Access to remove a resource. Does not apply to functions.</td>
    </tr>
    <tr>
        <td>Permission.write()</td>
        <td>Alias to grant create, update, and delete access for collections and buckets and update and delete access for documents and files.</td>
    </tr>
    </tbody>
</table>


<h2 id="permission-roles"><a href="/docs/permissions#permission-roles">Permission Roles</a></h2>
<p>In Client and Server SDKs, you will find a <b>Role</b> class with helper methods for each role described below.</p>
<table class="full text-size-small">
    <thead>
    <tr>
        <td style="width: 200px">Type</td>
        <td>Description</td>
    </tr>
    </thead>
    <tbody>
    <tr>
        <td>Role.any()</td>
        <td>Grants access to anyone.</td>
    </tr>
    <tr>
        <td>Role.guests()</td>
        <td>Grants access to any guest user without a session. Authenticated users don't have access to this role.</td>
    </tr>
    <tr>
        <td>Role.users([STATUS])</td>
        <td>Grants access to any authenticated or anonymous user. You can optionally pass the <span class="tag">verified</span> or <span class="tag">unverified</span> string to target specific types of users.</td>
    </tr>
    <tr>
        <td>Role.user([USER_ID], [STATUS])</td>
        <td>Grants access to a specific user by user ID. You can optionally pass the <span class="tag">verified</span> or <span class="tag">unverified</span> string to target specific types of users.</td>
    </tr>
    <tr>
        <td>Role.team([TEAM_ID])</td>
        <td>Grants access to any member of the specific team. To gain access to this permission, the user must be the team creator (owner), or receive and accept an invitation to join this team.</td>
    </tr>
    <tr>
        <td>Role.team([TEAM_ID], [ROLE])</td>
        <td>Grants access to any member who possesses a specific role in a team. To gain access to this permission, the user must be a member of the specific team and have the given role assigned to them. Team roles can be assigned when inviting a user to become a team member.</td>
    </tr>
    <tr>
        <td>Role.member([MEMBERSHIP_ID])</td>
        <td>Grants access to a specific member of a team. When the member is removed from the team, they will no longer have access.</td>
    </tr>
    <tr>
        <td>Role.label([LABEL_ID])</td>
        <td>Grants access to all accounts with a specific label ID. Once the label is removed from the user, they will no longer have access. <a href="/docs/authentication-management#labels">Learn more about labels</a>.</td>
    </tr>
    </tbody>
</table>

<h2 id="examples"><a href="/docs/permissions#examples">Examples</a></h2>

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

<p>The following examples are using the <a href="https://github.com/appwrite/sdk-for-js" target="_blank" rel="noopener">Appwrite Web SDK</a> but can be applied similarly to any of the other <a href="/docs/sdks">Appwrite SDKs</a>.</p>

<h3 id="example-1"><a href="/docs/permissions#example-1">Example #1 - Basic Usage</a></h3>

<p>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 <span class="tag">user:5c1f88b42259e</span>.</p>

<div class="ide" data-lang="javascript" data-lang-label="Web SDK">
    <pre class="line-numbers"><code class="prism language-javascript" data-prism>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);
});</code></pre>
</div>

<h3 id="example-2"><a href="/docs/permissions#example-2">Example #2 - Team Roles</a></h3>

<p>In the following example, we are creating a document that can be read by members of the team with ID <span class="tag">5c1f88b87435e</span> and can only be edited or deleted by members of the same team that possess the team role <span class="tag">owner</span>.</p>

<div class="ide" data-lang="javascript" data-lang-label="Web SDK">
    <pre class="line-numbers"><code class="prism language-javascript" data-prism>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);
});</code></pre>
</div>
