> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Appwrite

> Connect an Appwrite Cloud project to Oleria to discover its users, teams, roles, data access, non-human identities, stored secrets, and audit activity.

Connect Appwrite to Oleria to see who can reach the data in the applications you build on Appwrite. Oleria reads a project's users, teams, team roles and labels, who can read and write each database table, storage bucket, and function, the project's API keys, functions, and sites, the secrets Appwrite stores for the project, and the project's audit log. You can then find dormant, public, or over-privileged access and act on it directly from Oleria.

> [!NOTE]
>
> This integration supports **Appwrite Cloud** only. Self-hosted Appwrite isn't supported. Each integration connects one Appwrite project. If you have more than one, add an integration for each. See [Multi-instance support](/integrations/overview.md#multi-instance-support).

## What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from your Appwrite project:

* **Accounts** - every user of the project. For each user, Oleria shows:
  * **Name, email, and phone**, and whether the email and phone are verified.
  * **Status** - blocked users show as disabled.
  * **MFA** - whether multi-factor authentication is required for the user, and the factors they have set up (authenticator app, email, or phone).
  * **Sign-in methods** - password, the OAuth2 providers the user has signed in with, and their MFA factors. A user who signs in through an OAuth2 provider is marked as using single sign-on.
  * **Last activity** - the last time the user made a signed-in request, used for dormant account detection.
  * **Last password change.**

* **Public and project-wide access** - Appwrite permissions can be granted to roles that aren't individual users. Oleria shows them so that public access is visible:
  * **Anyone (public)** and **Guests** appear as accounts.
  * **All users**, **Verified users**, and **Unverified users** appear as groups, with every matching user as a member.

* **Teams** - every team and its confirmed members. Members with the team's **owner** role are shown as the team's owners. Invitations that haven't been accepted grant nothing, so they aren't shown as members.

* **Roles**:
  * **Labels** - the labels assigned to users, which Appwrite uses as roles in permissions.
  * **Team roles** - each role within a team, such as `Engineering/owner`, held by the team members who have it.
  * **Console roles** - **Owner**, **Developer**, **Editor**, **Analyst**, and **Billing**. Console roles give implied access to every database, bucket, and function in the project. The console members who hold them appear only if you add an organization API key (see [Connect Appwrite to Oleria](#connect-appwrite-to-oleria)).

* **Resources** - every TablesDB database and its tables, every storage bucket, and every function, each with a link to it in the Appwrite Console. For each resource, Oleria shows who can create, read, update, and delete it (or, for a function, who can execute it), from the resource's permissions. Whether row or file security is turned on is shown on the table or bucket.

* **Impersonation** - users allowed to impersonate other users are shown as able to act as any user of the project.

* **Non-human identities (NHIs) and credentials:**

  | Identity | Shown as |
  | :- | :- |
  | API keys | API token, with its scopes, expiry, and last-used date, and a matching credential. Oleria never stores the key itself. Its data scopes are shown as access (see below). |
  | Functions | Application, also shown as a resource with its execute access. |
  | Sites | Application. |
  | OAuth2 sign-in providers that have a client ID set | Credential only (not a non-human identity). Disabled providers that still hold a secret are shown as disabled. Disable NHI doesn't apply. |
  | Messaging providers (email, SMS, and push) | Credential only (not a non-human identity). Disable NHI doesn't apply. |
  | Webhooks | Credential only, for the webhook's signing secret, with its target host. Disable NHI doesn't apply. |
  | Custom SMTP server | Credential only, for the SMTP password. Disable NHI doesn't apply. |

* **Access through API scopes** - Appwrite API keys, and the keys functions and sites run with, ignore resource permissions: a scope such as `rows.read` reaches every table in the project. Oleria shows this as access from the key, function, or site to every database, bucket, or function its scopes cover. Expired keys and disabled functions and sites are left out.

* **Activity** - events from the project's audit log, attributed to the user or API key that performed them: sign-ins and sign-outs, password recovery, users, teams, and memberships created, changed, and removed, API keys, webhooks, OAuth2 providers, and messaging providers added and changed, and databases, tables, buckets, files, functions, and sites created, changed, and removed. Other events keep their Appwrite event name. Events performed by console members are attributed to them only if you add an organization API key.

Oleria refreshes this data on its [regular sync schedule](/integrations/overview.md#sync-model).

> [!NOTE]
>
> Appwrite has no AI agent objects, so none appear.

## Prerequisites

* An **Appwrite Cloud** project on any plan. The Free plan works. Some data depends on your plan; see [Known limitations](#known-limitations).
* A member of the project's organization with the **Owner** or **Developer** role, to create the API key. Appwrite gives both roles access to all of a project's development resources.
* Admin access on the Oleria platform to add a new integration.

## Create an API key in Appwrite

Oleria uses one project API key for both discovery and remediation actions. Its scopes decide what Oleria can do.

> [!NOTE]
>
> The exact location of these settings can change over time. If the steps below don't match what you see, refer to Appwrite's [API keys](https://appwrite.io/docs/partners/project/api-keys) documentation.

**1. Open the API keys page**

Sign in to the [Appwrite Console](https://cloud.appwrite.io) and open the project you want to connect. In the sidebar, select **API Keys**, then select **Create API key**.

**2. Name the key and choose an expiration**

Enter a name, such as `Oleria`, and choose an expiration that fits your policy.

**3. Select the scopes**

Select these scopes for discovery:

| Scope | Used for |
| :- | :- |
| `users.read` | Users, labels, MFA factors, and sign-in identities |
| `teams.read` | Teams, members, and team roles |
| `project.read` | The project |
| `keys.read` | API keys |
| `functions.read` | Functions |
| `sites.read` | Sites |
| `databases.read`, `tables.read` | Databases and tables, and their permissions |
| `buckets.read` | Storage buckets and their permissions |
| `project.oauth2.read` | OAuth2 sign-in providers |
| `project.policies.read` | The project's authentication policies |
| `providers.read` | Messaging providers |
| `webhooks.read` | Webhooks |
| `events.read` | Activity |

To let Oleria run [remediation actions](#remediation-actions), also select:

| Scope | Used for |
| :- | :- |
| `users.write` | Create, block, unblock, and delete users; sign users out; add and remove labels |
| `teams.write` | Create teams; add and remove team members; add and remove team roles |
| `keys.write` | Disable API keys |
| `functions.write` | Disable functions; revoke access to functions |
| `sites.write` | Disable sites |
| `tables.write` | Revoke access to tables |
| `buckets.write` | Revoke access to buckets |

Only `users.read`, `teams.read`, and `project.read` are required. If another read scope is missing, Oleria skips that data and syncs everything else.

**4. Copy the key**

Select **Create API key**, then copy the key.

**5. Copy the project ID and region**

In the project's **Settings**, copy the **Project ID**. Note the region in the project's API endpoint, for example `fra` in `https://fra.cloud.appwrite.io/v1`.

> [!WARNING]
>
> Treat the API key like a password. It can do anything its scopes allow in the project.

> [!NOTE]
>
> If you set an expiration, add a reminder to create a new key and update the integration before it expires. When the key expires, the integration stops syncing until you update it.

### Organization API key (optional)

To see the console members who administer the project, and their console roles, add an organization API key with the scopes `organization.read` and `organization.memberships.read`, together with your **Organization ID** from the organization's **Settings**. Organization API keys aren't available on every Appwrite plan; the Free plan doesn't offer them. Without one, Oleria still shows the access that console roles give, but not who holds them.

## Connect Appwrite to Oleria

**1. Open the integration**

Go to your Oleria workspace, select **Integrations**, select the **Available** tab, and search for **Appwrite**.

**2. Complete the connection form**

Select the **Appwrite** card and fill in the connection form:

| Field | Notes |
| :- | :- |
| **Region** | Required. The region in your project's API endpoint: `fra`, `nyc`, `syd`, `sfo`, `sgp`, or `tor`. |
| **Project ID** | Required. The project to connect. |
| **API Key** | Required. The project API key you created. |
| **Organization ID** | Optional. Enter it together with the organization API key. |
| **Organization API Key** | Optional. For console members and their console roles. |

**3. Authenticate**

Select **Authenticate**. Before saving the integration, Oleria checks that the API key is valid and belongs to the project you entered, and, if you added one, that the organization API key is valid for the organization.

If **Authenticate** fails, the message says what's wrong:

* **Appwrite rejected the ... (HTTP 401 ...)** - the key is invalid or has expired, or the Project ID or Organization ID is wrong. Check the key and IDs, or create a new key.
* **The ... is missing a required scope** - add the listed scope to the key in Appwrite.
* **The API key belongs to a different Appwrite project** - the key was created in another project. Check the **Project ID**, or create the key in the project you're connecting.
* **Appwrite could not find the project in this region** - check the **Region** and **Project ID**.

When you edit the integration, leave a key field blank to keep the stored key.

## Verify the integration

Confirm the new instance appears on the **Connected** tab of your Oleria **Integrations** page with a status of **Healthy**. After the first sync completes, review the discovered accounts, teams, roles, resources, NHIs, and activity in your Oleria workspace.

If something you expect is missing, check that the API key has the scopes in the table above.

## Remediation actions

Oleria can take these actions in Appwrite. Each action needs the write scopes listed above.

| Action | What it does | Reversible? |
| :- | :- | :- |
| Create user | Creates a user with the given name and email, and adds them to the selected teams. Unless the action asks for an active account, the user is created blocked. If a user with the email exists, nothing changes. | Yes - Oleria deletes the user it created. |
| Disable user | Blocks the user. | Yes - reversed by unblocking the user. |
| Enable user | Unblocks the user. | Yes - reversed by blocking the user again. |
| Add user to team | Adds the user to a team as a confirmed member. | Yes - reversed by removing the user from the team. |
| Remove user from team | Removes the user's team membership. | Yes - the user is added back with their previous team roles. |
| Add role | Adds a label to the user, or adds a team role to the user's membership in that team. | Yes - reversed by removing the label or team role. |
| Remove role | Removes a label from the user, or removes a team role from the user's membership. | Yes - the label or team role is added back. |
| Disable NHI | Depends on the NHI: expires an API key immediately, or turns off a function or site. Every other setting of the function or site is kept. | Yes - the API key's previous expiration is restored, or the function or site is turned back on. |
| Revoke resource permission | Removes a user's, team's, team role's, or label's direct permissions on a table, bucket, or function. For a user, this includes permissions granted to their team memberships. Every other setting of the resource is kept. | Yes - the removed permissions are added back. |
| Revoke anonymous access | Removes **Anyone** and **Guests** permissions from a table, bucket, or function. | Yes - the removed permissions are added back. |
| Revoke user sessions | Signs the user out of every session. | No - the user signs in again. |
| Delete user | Deletes the user. | No - Appwrite can't restore a deleted user. A re-created user gets a new ID. |
| Create team | Creates a team. If a team with the same name exists, nothing changes. | Yes - Oleria deletes the team it created, as long as no members have been added to it. |

A few safeguards apply to every action:

* Oleria won't disable the API key the integration uses. Doing so would disconnect the integration.
* Oleria won't add a team role to a user who isn't a member of the team. Add the user to the team first.
* Oleria won't add a user to a team while they have a pending invitation to it. Appwrite doesn't let an API key accept an invitation for a user. Remove the invitation in Appwrite, or let the user accept it.
* **All users**, **Verified users**, **Unverified users**, **Anyone**, and **Guests** follow from Appwrite's permission rules, so their membership can't be changed.
* Revoking a resource permission removes only direct permissions. If a user has no direct permission but still has access through a team, a team role, a label, **All users**, or **Anyone**, the action fails and names those, so you can remove that access instead. If direct permissions are removed but such access remains, the result lists it. Access from console roles and API scopes can't be revoked from Oleria, and TablesDB databases have no permissions of their own, so revoke access on their tables.
* If the user or NHI already has the state an action asks for, the action succeeds and changes nothing.

## Known limitations

* **Rows, documents, and files aren't inventoried.** Permissions on individual rows and files aren't shown. Whether row or file security is turned on is shown on the table or bucket.
* **Some database types aren't inventoried.** DocumentsDB, VectorsDB, and native PostgreSQL and MySQL databases aren't shown, nor are legacy Databases collections.
* **Console members need an organization API key.** Without one, the access console roles give is shown, but not who holds them, and actions performed by console members appear without an actor.
* **API keys, functions, and sites have no owner.** Appwrite doesn't record who created them.
* **File tokens aren't inventoried.**
* **Conditional permissions are simplified.** A permission granted to a user only while they're verified, such as `user:<id>/verified`, is shown as granted to the user.
* **Audit history depends on your plan.** Appwrite keeps audit events for one hour on the Free plan and longer on paid plans. Oleria collects what Appwrite still holds at each sync.
* **Some data depends on your plan.** Organization API keys and custom SMTP aren't available on the Free plan, so console members and the SMTP password don't appear there.
* **Self-hosted Appwrite isn't supported.**

## Contact us

For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.