From 7a5c8f69c6a41f7805c5ae34b51ab42f5e0dea55 Mon Sep 17 00:00:00 2001 From: Phillip Jones Date: Fri, 19 Jul 2024 10:17:29 -0700 Subject: [PATCH] Add documentation on creating R2 API tokens via API (#15711) * Add documentation on creating R2 API tokens via API * Removed Account resource type description, collapsed permission group tables * Moving temp access credentials to the bottom --- content/r2/api/s3/tokens.md | 127 +++++++++++++++++++++++++++++++++++- 1 file changed, 126 insertions(+), 1 deletion(-) diff --git a/content/r2/api/s3/tokens.md b/content/r2/api/s3/tokens.md index b1b8666fef4937..aa9ae690ca2bda 100644 --- a/content/r2/api/s3/tokens.md +++ b/content/r2/api/s3/tokens.md @@ -47,11 +47,136 @@ Jurisdictional buckets can only be accessed via the corresponding jurisdictional | Permission | Description | |------------|-------------| -| Admin Read and Write | Allows the ability to create, list and delete buckets, and edit bucket configurations in addition to list, write, and read object access. | +| Admin Read & Write | Allows the ability to create, list and delete buckets, and edit bucket configurations in addition to list, write, and read object access. | | Admin Read only | Allows the ability to list buckets and view bucket configuration in addition to list and read object access. | | Object Read & Write | Allows the ability to read, write, and list objects in specific buckets. | | Object Read only | Allows the ability to read and list objects in specific buckets. | +## Create API tokens via API + +You can create API tokens via the API and use them to generate corresponding Access Key ID and Secret Access Key values. To get started, refer to [Create API tokens via the API](/fundamentals/api/how-to/create-via-api/). Below are the specifics for R2. + +### Access Policy + +An Access Policy specifies what resources the token can access and the permissions it has. + +#### Resources + +There are two relevant resource types for R2: `Account` and `Bucket`. For more information on the Account resource type, refer to [Account](/fundamentals/api/how-to/create-via-api/#account). + +##### Bucket + +Include a set of R2 buckets or all buckets in an account. + +A specific bucket is represented as: + +```json +"com.cloudflare.edge.r2.bucket.__": "*" +``` + +- `ACCOUNT_ID`: Refer to [Find zone and account IDs](/fundamentals/setup/find-account-and-zone-ids/#find-account-id-workers-and-pages). +- `JURISDICTION`: The [jurisdiction](/r2/reference/data-location/#available-jurisdictions) where the R2 bucket lives. For buckets not created in a specific jurisdiction this value will be `default`. +- `BUCKET_NAME`: The name of the bucket your Access Policy applies to. + +All buckets in an account are represented as: + +```json +"com.cloudflare.api.account.": { + "com.cloudflare.edge.r2.bucket.*": "*" +} +``` + +- `ACCOUNT_ID`: Refer to [Find zone and account IDs](/fundamentals/setup/find-account-and-zone-ids/#find-account-id-workers-and-pages). + +#### Permission groups + +Determine what [permission groups](/fundamentals/api/how-to/create-via-api/#permission-groups) should be applied. There are four relevant permission groups for R2. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Permission group + + Resource + + Permission +
+ Workers R2 Storage Write + + Account + + Admin Read & Write +
+ Workers R2 Storage Read + + Account + + Admin Read only +
+ Workers R2 Storage Bucket Item Write + + Bucket + + Object Read & Write +
+ Workers R2 Storage Bucket Item Read + + Bucket + + Object Read only +
+ +#### Example Access Policy + +```json +[ + { + "id": "f267e341f3dd4697bd3b9f71dd96247f", + "effect": "allow", + "resources": { + "com.cloudflare.edge.r2.bucket.4793d734c0b8e484dfc37ec392b5fa8a_default_my-bucket": "*", + "com.cloudflare.edge.r2.bucket.4793d734c0b8e484dfc37ec392b5fa8a_eu_my-eu-bucket": "*" + }, + "permission_groups": [ + { + "id": "6a018a9f2fc74eb6b293b0c548f38b39", + "name": "Workers R2 Storage Bucket Item Read" + } + ] + } +] +``` + +### Get S3 API credentials from an API token + +You can get the Access Key ID and Secret Access Key values from the response of the [Create Token](/api/operations/user-api-tokens-create-token) API: +- Access Key ID: The `id` of the API token. +- Secret Access Key: The SHA-256 hash of the API token `value`. + ## Temporary access credentials If you need to create temporary credentials for a bucket or a prefix/object within a bucket, you can use the [temp-access-credentials endpoint](/api/operations/r2-create-temp-access-credentials) in the API. You will need an existing R2 token to pass in as the parent access key id. You can use the credentials from the API result for an S3-compatible request by setting the credential variables like so: