# Access Control

When you create access keys through the Partner API, three fields control what those keys can do:

* `user_role` tells Tigris what the user in `user_id` can do in **this Partner API call**: which access keys the call can manage, and which bucket roles it can grant.
* `buckets_roles` controls what **S3 operations** the access key can perform on specific buckets.
* `access_key_scope` controls whether the key also receives [default allowed operations](https://www.tigrisdata.com/docs/iam/manage-access-key.md#default-allowed-operations) such as create bucket and list buckets.

`buckets_roles` and `access_key_scope` are stored on the access key and apply to every request the key makes. `user_role` applies only to the call that you pass it on. Tigris does not store it on the key.

| Field              | Where it applies     | What it controls                                                 |
| ------------------ | -------------------- | ---------------------------------------------------------------- |
| `user_role`        | One Partner API call | Which keys the call can manage and which bucket roles it can set |
| `buckets_roles`    | S3 requests          | What the access key can read, write, or manage per bucket        |
| `access_key_scope` | S3 and IAM requests  | Whether the key receives default allowed operations              |

<!-- -->

## Organization Role (`user_role`)[​](#organization-role-user_role "Direct link to organization-role-user_role")

The `user_role` field tells Tigris what privileges this user has in your system. You pass it on provisioning and access key calls.

| Value    | What the call can do                                                                                                                                                                 |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Admin`  | View, update, rotate, and delete any access key in the org. Grant any bucket role on any bucket in the org, including `"*"`.                                                         |
| `Member` | View, rotate, and delete only the access keys of `user_id`. Change the bucket roles and the scope of only those keys. Grant bucket roles only on buckets that `user_id` provisioned. |

The behavioral difference shows up immediately. When you call [List Access Keys](https://www.tigrisdata.com/docs/partner-integrations/api/tigris-list-access-keys/) with `user_role: "Admin"`, the response includes **all** access keys in the org. With `user_role: "Member"` (or omitted), you get back **only keys owned by that user**.

If you omit `user_role`, the call is treated as `Member`. A `Member` call that grants a role on a bucket that `user_id` did not provision fails with a permission error. If your backend manages access for all of your users, pass `user_role: "Admin"`.

`user_role` does not limit IAM policies. A `Member` call can create a policy for any bucket in the org. It can also attach a policy to, or detach a policy from, any access key in the org.

The access key that the call creates does not become an admin. Its access comes only from its `buckets_roles`, its `access_key_scope`, and its IAM policies.

## Bucket Roles (`buckets_roles`)[​](#bucket-roles-buckets_roles "Direct link to bucket-roles-buckets_roles")

The `buckets_roles` field is an array of `{bucket_name, role}` pairs stored on the access key. See the [RBAC permissions table](https://www.tigrisdata.com/docs/concepts/authnz.md#role-based-access-control-rbac) for exactly which S3 operations each role permits.

| Role        | What the key can do on the bucket                                                                                                    |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `ReadOnly`  | Read and list objects. Create snapshots and forks.                                                                                   |
| `ReadWrite` | Everything in `ReadOnly`, plus write and delete objects. It cannot change bucket settings or delete the bucket.                      |
| `Editor`    | Everything in `ReadWrite`, plus bucket settings, public access, and bucket deletion. It cannot manage bucket shares or IAM policies. |
| `Admin`     | Every operation on every bucket in the org. Use it only with `"bucket_name": "*"`.                                                   |

Use `"*"` as the bucket name to give a role on all buckets in the org, including buckets created later. A key can have only one `"*"` entry, and only a `user_role: "Admin"` call can grant it.

`{"bucket_name": "*", "role": "Admin"}` must be the only entry on the key. That key is a full org admin. It can do every operation on every bucket, except the deletes that [delete protection](#how-tigris-evaluates-a-request) blocks.

## Access Key Scope (`access_key_scope`)[​](#access-key-scope "Direct link to access-key-scope")

This field controls the [default allowed operations](https://www.tigrisdata.com/docs/iam/manage-access-key.md#default-allowed-operations) on the key. A standard key can create buckets, list buckets, and manage its own access keys and IAM policies, even with no bucket role.

| Value                | What it means                                            |
| -------------------- | -------------------------------------------------------- |
| `standard` (default) | The key receives the default allowed operations.         |
| `no_default_allow`   | The key does not receive the default allowed operations. |

If you omit `access_key_scope`, the key uses `standard`. You can set the field on [Provision](https://www.tigrisdata.com/docs/partner-integrations/api/tigris-provisioning/), [Create Access Key](https://www.tigrisdata.com/docs/partner-integrations/api/tigris-create-access-key/), and [Update Access Key](https://www.tigrisdata.com/docs/partner-integrations/api/tigris-update-access-key/). If you omit the field on update, the current scope stays unchanged.

A key that creates a bucket becomes the owner of that bucket, and an owner can do every operation on it. Use `no_default_allow` for keys that you give to your users, so that they cannot create buckets that they own.

## The Provisioned Access Key[​](#the-provisioned-access-key "Direct link to The Provisioned Access Key")

[Provision](https://www.tigrisdata.com/docs/partner-integrations/api/tigris-provisioning/) returns an access key, and that key is the **owner** of the bucket it provisions. The owner can do every operation on the bucket. It can delete the bucket, change its settings, and turn off soft delete. Bucket roles, IAM policies, and `access_key_scope` cannot limit what an owner can do on its bucket.

Keep the provisioned key in your backend, or delete it. Give your users a separate key that has only the access they need. See [Give Users Data Access Without Bucket Admin](#give-users-data-access-without-bucket-admin).

Each Provision call creates a new owner key. If your backend manages the bucket with the Partner API, it does not need this key. You can delete the key with [Delete Access Key](https://www.tigrisdata.com/docs/partner-integrations/api/tigris-delete-access-key/) after Provision. The Partner API calls for the bucket continue to work, and no access key owns the bucket.

If your users already have the provisioned key, see [Move Users Off the Provisioned Key](#move-users-off-the-provisioned-key).

## How Tigris Evaluates a Request[​](#how-tigris-evaluates-a-request "Direct link to How Tigris Evaluates a Request")

Tigris checks each S3 request in this order. It stops at the first step that gives a result.

| Step | Check                                                                     | Result        |
| ---- | ------------------------------------------------------------------------- | ------------- |
| 1    | The bucket has delete protection and the request deletes a bucket or data | Deny          |
| 2    | The key has `{"bucket_name": "*", "role": "Admin"}`                       | Allow         |
| 3    | The key owns the bucket                                                   | Allow         |
| 4    | A bucket role on the key permits the operation                            | Allow         |
| 5    | An IAM policy on the key matches. A `Deny` statement wins over an `Allow` | Deny or allow |
| 6    | The key uses `standard` and the operation is a default allowed operation  | Allow         |
| 7    | No step gave a result                                                     | Deny          |

A policy cannot take away an operation that steps 2 to 4 allow. For example, a `Deny` on `s3:DeleteBucket` has no effect on a key with the `Editor` role, because the role allows the delete at step 4. To limit a key, give it a smaller role, or give it no role and grant access with a policy.

## Permission Recipes[​](#permission-recipes "Direct link to Permission Recipes")

Each recipe shows one request. Replace the IDs and bucket names with your own.

The recipes that grant a bucket role use `user_role: "Admin"`, so that your backend can grant a role on any bucket in the org. You can use `Member` instead when `user_id` is the user that provisioned the bucket.

### Give Users Data Access Without Bucket Admin[​](#give-users-data-access-without-bucket-admin "Direct link to Give Users Data Access Without Bucket Admin")

Use this recipe when your users read and write their own data and your backend manages the buckets.

```
POST /v1/providers/{provider_id}/orgs/{org_id}/key

Content-Type: application/json



{

  "user_id": "user-123",

  "user_role": "Admin",

  "name": "user-123-data",

  "access_key_scope": "no_default_allow",

  "buckets_roles": [

    { "bucket_name": "user-data", "role": "ReadWrite" }

  ]

}
```

The key can read, write, and delete objects in `user-data`. It cannot delete the bucket, change bucket settings, turn off soft delete, create buckets, or create access keys.

### Move Users Off the Provisioned Key[​](#move-users-off-the-provisioned-key "Direct link to Move Users Off the Provisioned Key")

Use this recipe when your users already have the provisioned key. You cannot move the ownership of a bucket to a different key. You must replace the secret of the provisioned key instead.

With the provisioned key, a user can create more access keys. These keys continue to work after you rotate the provisioned key. You must also delete them.

1. Create a key for the user with the [Give Users Data Access Without Bucket Admin](#give-users-data-access-without-bucket-admin) recipe. Give the new key to the user.

2. Rotate the provisioned key with [Rotate Access Key](https://www.tigrisdata.com/docs/partner-integrations/api/tigris-rotate-access-key/):

   ```
   POST /v1/providers/{provider_id}/orgs/{org_id}/key/rotate

   Content-Type: application/json



   {

     "user_id": "user-123",

     "user_role": "Admin",

     "id": "tid_provisioned_key_id"

   }
   ```

3. Keep the new secret from the response in your backend.

4. Get all of the access keys in the org with [List Access Keys](https://www.tigrisdata.com/docs/partner-integrations/api/tigris-list-access-keys/) and `user_role: "Admin"`.

5. If a key is not in the records of your backend, delete it with [Delete Access Key](https://www.tigrisdata.com/docs/partner-integrations/api/tigris-delete-access-key/).

The old secret and the deleted keys can continue to work for up to 15 minutes.

### Read-Only Access to One Bucket[​](#read-only-access-to-one-bucket "Direct link to Read-Only Access to One Bucket")

```
POST /v1/providers/{provider_id}/orgs/{org_id}/key

Content-Type: application/json



{

  "user_id": "user-123",

  "user_role": "Admin",

  "access_key_scope": "no_default_allow",

  "buckets_roles": [

    { "bucket_name": "assets", "role": "ReadOnly" }

  ]

}
```

The key can read and list objects in `assets`. It cannot write or delete objects, and it cannot list or create buckets.

### Read-Only Access to All Buckets[​](#read-only-access-to-all-buckets "Direct link to Read-Only Access to All Buckets")

```
POST /v1/providers/{provider_id}/orgs/{org_id}/key

Content-Type: application/json



{

  "user_id": "reporting",

  "user_role": "Admin",

  "access_key_scope": "no_default_allow",

  "buckets_roles": [

    { "bucket_name": "*", "role": "ReadOnly" }

  ]

}
```

The key can read every bucket in the org, including buckets created later. Only a `user_role: "Admin"` call can grant a role on `"*"`.

### Different Access per Bucket[​](#different-access-per-bucket "Direct link to Different Access per Bucket")

```
POST /v1/providers/{provider_id}/orgs/{org_id}/key

Content-Type: application/json



{

  "user_id": "user-123",

  "user_role": "Admin",

  "access_key_scope": "no_default_allow",

  "buckets_roles": [

    { "bucket_name": "assets", "role": "ReadOnly" },

    { "bucket_name": "uploads", "role": "ReadWrite" }

  ]

}
```

The key can read `assets`, and it can read and write `uploads`.

### Upload-Only Key[​](#upload-only-key "Direct link to Upload-Only Key")

Use a policy for this recipe, because no bucket role allows uploads without reads. The key gets no bucket role, so Tigris evaluates the policy.

```
POST /v1/providers/{provider_id}/orgs/{org_id}/key

Content-Type: application/json



{

  "user_id": "user-123",

  "name": "uploader",

  "access_key_scope": "no_default_allow",

  "create_policies": [

    {

      "name": "uploads-put-only",

      "document": {

        "Version": "2012-10-17",

        "Statement": [

          {

            "Effect": "Allow",

            "Action": ["s3:PutObject", "s3:AbortMultipartUpload"],

            "Resource": ["arn:aws:s3:::uploads/*"]

          }

        ]

      }

    }

  ]

}
```

The key can upload objects to `uploads`, with multipart uploads too. It cannot read, list, or delete objects. It can overwrite an object that has the same name.

`s3:PutObject` covers the create, upload part, and complete steps of a multipart upload. Tigris rejects `s3:CreateMultipartUpload` and `s3:UploadPart` in a policy.

Policy names are unique in the org. To give the same policy to more keys, create it one time, then pass its name in `attach_policies`.

### Backend Admin Key[​](#backend-admin-key "Direct link to Backend Admin Key")

Your backend can use the provisioned key for its bucket. To manage all buckets in the org from one key, create an org admin key:

```
POST /v1/providers/{provider_id}/orgs/{org_id}/key

Content-Type: application/json



{

  "user_id": "platform-backend",

  "user_role": "Admin",

  "buckets_roles": [

    { "bucket_name": "*", "role": "Admin" }

  ]

}
```

warning

Keep this key in your backend. Do not give it to your users. The key can delete every bucket in the org.

### Protect Buckets From Accidental Deletion[​](#protect-buckets-from-accidental-deletion "Direct link to Protect Buckets From Accidental Deletion")

Turn on [soft delete](https://www.tigrisdata.com/docs/buckets/soft-delete.md) when you provision the bucket:

```
POST /v1/providers/{provider_id}/orgs/{org_id}/provision

Content-Type: application/json



{

  "bucket_name": "user-data",

  "org_name": "Acme Corp",

  "user_id": "user-123",

  "bucket_options": {

    "soft_delete": { "enabled": true, "retention_days": 30 }

  }

}
```

For an existing bucket, use [Set Soft Delete](https://www.tigrisdata.com/docs/partner-integrations/api/tigris-set-soft-delete/).

When a user deletes the bucket, it moves to the deleted buckets list. Use [List Deleted Buckets](https://www.tigrisdata.com/docs/partner-integrations/api/tigris-list-deleted-buckets/) to find it, and [Restore Bucket](https://www.tigrisdata.com/docs/partner-integrations/api/tigris-restore-bucket/) to bring it back.

A soft-deleted bucket stays until you restore it or [delete it permanently](https://www.tigrisdata.com/docs/partner-integrations/api/tigris-purge-bucket/). It counts toward storage usage until then.

Soft delete protects the bucket from a usual delete request. It does not stop a key that can change bucket settings:

* The bucket owner, `Editor` keys, and org admin keys can turn off soft delete.
* These keys can also permanently delete a soft-deleted bucket over S3.
* A `ReadWrite` key cannot do these operations.

### Change Bucket Settings for Your Users[​](#change-bucket-settings-for-your-users "Direct link to Change Bucket Settings for Your Users")

No bucket role allows bucket settings without bucket deletion. `Editor` includes `DeleteBucket`, and a policy cannot take it away (see [How Tigris Evaluates a Request](#how-tigris-evaluates-a-request)).

Keep your users on `ReadWrite`, and change bucket settings from your backend with the Partner API:

* [Update Bucket](https://www.tigrisdata.com/docs/partner-integrations/api/tigris-update-bucket/) for public access, storage class, regions, and object notifications
* [Set Lifecycle Rules](https://www.tigrisdata.com/docs/partner-integrations/api/tigris-set-lifecycle-rules/)
* [Attach a Custom Domain](https://www.tigrisdata.com/docs/partner-integrations/api/tigris-set-custom-domain/)
* [Set Soft Delete](https://www.tigrisdata.com/docs/partner-integrations/api/tigris-set-soft-delete/)

### Rotate or Revoke a Key[​](#rotate-or-revoke-a-key "Direct link to Rotate or Revoke a Key")

To replace a leaked secret, call [Rotate Access Key](https://www.tigrisdata.com/docs/partner-integrations/api/tigris-rotate-access-key/). It returns a new secret and keeps the key ID, so the key keeps its roles, policies, and bucket ownership.

To revoke a key, call [Delete Access Key](https://www.tigrisdata.com/docs/partner-integrations/api/tigris-delete-access-key/). Deleting a key does not delete the buckets that it owns.

note

After you rotate or delete a key, the old secret can continue to work for up to 15 minutes. After you change the bucket roles or the scope of a key, the old access can also continue for up to 15 minutes.

A `Member` call can rotate or delete only the keys of its `user_id`. A `user_role: "Admin"` call can rotate or delete any key in the org.

## Fine-Grained Access with IAM Policies[​](#fine-grained-access-with-iam-policies "Direct link to Fine-Grained Access with IAM Policies")

For access that bucket roles cannot give, use [IAM policies](https://www.tigrisdata.com/docs/iam/policies.md). You can create a policy with [Create Policy](https://www.tigrisdata.com/docs/partner-integrations/api/tigris-create-policy/) and attach it with `attach_policies` on Create Access Key or `add_policies` on Update Access Key. You can also create and attach a policy in one call with `create_policies`.

Policies only add access. Tigris reads them only when the key's bucket roles and bucket ownership do not already allow the operation (see [How Tigris Evaluates a Request](#how-tigris-evaluates-a-request)):

* To grant access with a policy, give the key no bucket role on that bucket.
* A `Deny` statement blocks only access that a policy or a default allowed operation gives. It does not block access that a bucket role, bucket ownership, or the `"*"` `Admin` role gives.
