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

# Authorization

> Configure who is authorized to access the Archil APIs or disk

Archil supports three different kinds of resources to authorize access to:

* The **Archil disk mount** for mounting the disk on Linux, on macOS, or inside containers.
* The **Archil API** for creating Archil disks or sandboxes
* The **Archil S3 API** for calling the S3-compatible API from AWS SDKs

## Disk mount authorization

Each Archil disk manages which servers are authorized to mount the disk using the `archil` CLI or macOS application. Authorizing
a server to mount the disk gives that server access to the *entire* file system. Even though Archil respects the POSIX permissions
of the files stored on the disk, they should not be used as an isolation boundary for unstrusted workloads running together.

Archil supports two ways to authorize a server to mount a disk:

1. **IAM-based authorization** - recommended when you are mounting a disk located in AWS from the same AWS region
2. **Token-based authorization** - recommended when you need the lowest disk mount latency

You configure the authorized users for your disk on the Archil console, on the disk details page, by selecting **Connetions**, and then
choosing to **Add User**, and selecting either a **Disk Token** or an **IAM User**, or via the [Add Disk User API](/api-reference/disk-users/add-user).

### IAM-based disk authorization

IAM-based disk authorization allows you to configure an AWS IAM role or user ARN that is allowed to mount the disk.
You can use the `archil utils get-iam-role` CLI command to get the IAM role ARN of the current EC2 instance.

You can mount a disk on an IAM-authorized server by running the `archil mount` command without any additional flags.

<Note>
  When using [AWS IAM Roles Anywhere](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/introduction.html), you must set the `AWS_EC2_METADATA_SERVICE_ENDPOINT` and `AWS_REGION` environment variables before mounting. These can be set inline with the mount command or exported in your shell session.
</Note>

### Token-based disk authorization

Token-based disk authorization allows you to create a long-lived bearer token that grants the ability to mount the disk.

You mount a disk using a token by setting the `ARCHIL_MOUNT_TOKEN` environment variable and passing it through sudo.

```bash theme={null}
export ARCHIL_MOUNT_TOKEN="<disk-token>"
sudo --preserve-env=ARCHIL_MOUNT_TOKEN archil mount <disk-name> /mnt/data --region <disk-region>
```

<Note>
  Using `--preserve-env=ARCHIL_MOUNT_TOKEN` passes the disk token through sudo's environment rather than the command line, preventing it from being visible in process listings (`ps aux`). This is more secure than both `sudo -E` (which passes all environment variables) and inline assignment (which exposes the token in the process list).
</Note>

Archil supports the ability to configure tokens to have a either a TTL (allowing mounts up for a period of time) or to be one-time use.
When the token expires, it can no longer be used to mount the disk, and read/write operations on the disk from that client will fail.

## API authorization

The Archil API allows you to create and manage Archil disks, disk users, and sandboxes -- including grep, SQLite, checkpoint, and S3 APIs.

You can authorize to the Archil API using an API key. You can create an API key on the Archil console, by selecting **API Keys**
from the sidebar and then clicking **Create API Key**.

Archil API keys are scoped to the organization or personal account which created them and a specific Archil region. This means that
an API key created for "aws-us-east-1" will not work to manage disks in "aws-us-west-2". API keys have full access to disks in the
organization or personal account which created them, including the ability to read data, delete disks, and run sandboxes.

## S3 authorization

The Archil API supports S3 APIs such as PutObject, GetObject, DeleteObject, and ListObjectsV2. You only need to create an S3-specific
key if you plan on using out-of-the-box AWS S3 SDKs, which require a SigV4 signing access key and secret access key.

To create an S3 access key and secret access key, use the Archil console and navigate to the disk details page. Then select
**Connetions** from the sidebar, and then click **Add User**. Select **S3** as the user type, and then click **Create User**.

You can then use these keys to access your Archil disk through the AWS CLI:

```bash theme={null}
export AWS_ACCESS_KEY_ID=<your_access_key_id>
export AWS_SECRET_ACCESS_KEY=<your_secret_access_key>

aws s3 ls s3://dsk-abc123/ \
  --endpoint-url https://s3.green.us-east-1.aws.prod.archil.com
```