JWT login

You can extend Appwrite's APIs by building backend apps using Server SDKs. To secure your backend app's APIs, client apps must prove their identity against your backend app before accessing sensitive information. You can secure these APIs and enforce access permissions in your backend app by using JWT authentication.

If you are already authenticated on your client-side app and need your backend app to act on behalf of the user, this guide will walk you through the process.

Proof of Identity

Before making requests to your backend APIs, your client application needs to first create a session directly with Appwrite using the account service. This session will act like an ID card for the user and can be used to access resources in Appwrite. The client will only receive information accessible to the user based on the resources' permissions.

When you build backend APIs to extend Appwrite's functionality, these APIs should still respect access permissions to keep user data secure. Appwrite's backend SDKs allow you to securely act on behalf of a user with the same permissions by using JWT authentication.

JWT Authentication

JSON Web Tokens (JWTs) are a secure means to transfer information or claims between two parties. JWTs act like temporary copies of the user's ID card that allow Appwrite's Server SDKs to access information on behalf of a user.

You need to create a session using the Client SDKs before generating a JWT. The JWT will be a stateless proof of claim for the identity of the authenticated user and expire after 15 minutes or when the session is deleted.

You can generate a JWT like this on a Client SDK.

Your server application can use the JWT to act on behalf of the user by creating a Client instance with the JWT for each request it receives. To keep your API secure, discard the client object after each request.

Use JWTs tokens like this in a Server SDK.

When should I use JWTs?

JWT auth is useful when you need your backend app's Server SDK to be restricted by the same set of permissions.

If your backend app's Server SDK is using an API key, it will fetch all resources regardless of permissions. This means the Server SDK might fetch files and documents your user should not be able to see, which is not helpful when you need to act on behalf of a user.

If your backend app's Server SDK is using a JWT, it will only fetch resources your user has permissions to access.

Example

Here's an example collection of birthdays with the following documents. Notice how they all have different permissions.

If you're authenticated on the client-side as user-a and created a JWT 'eyJJ9.eyJ...886ca', you can pass this JWT to a Server SDK on the backend server to fetch only the birthdays user-a can read.

Only Kevin's birthday is returned and documents where user-A has no permissions to access are not returned.

{
  "total": 1,
  "documents": [
    {
      "name": "Kevin",
      "birthday": "2012-02-03T00:00:00.000+00:00",
      "$id": "ac5fc866ad1e",
      "$permissions": [
        "read(\"user:user-a\")"
      ],
      "$collectionId": "642f3592aa5fc856ad1e",
      "$databaseId": "642f358bf4084c662590",
      ...
    }
  ]
}

If the same request is made where the Server SDK's client is authenticated with an API key instead of a JWT, the results returned will be different.

This will return every document regardless of permissions, which could lead to privacy and security problems.

{
  "total": 3,
  "documents": [
    {
      "name": "Kevin",
      "birthday": "2012-02-03T00:00:00.000+00:00",
      "$id": "ac5fc866ad1e",
      "$permissions": [
        "read(\"user:user-a\")"
      ],
      "$collectionId": "642f3592aa5fc856ad1e",
      "$databaseId": "642f358bf4084c662590",
      ...
    },
    {
      "name": "Laura",
      "birthday": "1999-09-22T11:21:23.334+00:00",
      "$id": "bc7fc866ad1e",
      "$permissions": [
        "read(\"user:user-b\")"
      ],
      "$collectionId": "642f3592aa5fc856ad1e",
      "$databaseId": "642f358bf4084c662590",
      ...
    },
    {
      "name": "Bob",
      "birthday": "1982-05-11T12:31:39.381+00:00",
      "$id": "cc2fc886ad1e",
      "$permissions": [
        "read(\"user:user-c\")"
      ],
      "$collectionId": "642f3592aa5fc856ad1e",
      "$databaseId": "642f358bf4084c662590",
      ...
    }
  ]
}

If you're integrating existing backend services with Appwrite or adding backend endpoints to perform more complex logic, JWT authentication helps them behave similarly to actual Appwrite endpoints.