Skip to navigation

API Credentials

An S3 credential is a pair of keys — an Access Key ID and a Secret Access Key — that lets a program use your buckets. The AWS CLI, rclone, backup tools, and the S3 SDKs for Python, Node.js, Go and other languages all sign in with one. Think of the Access Key ID as a username and the Secret Access Key as its password.

Each credential belongs to one workspace and has one permission level. It works only with that workspace’s buckets.

S3 credentials are not the same as platform API tokens. An S3 credential reads and writes files through the S3 endpoint. A platform API token manages resources (VMs, buckets, networks) through the IBEE API.

Choose a permission level

Pick the lowest level that does the job:

Your program needs to…Permission levelBuckets
Download files, or create presigned download linksObject Read onlyAll buckets, or only the ones you pick
Upload, download and delete files, or create presigned upload linksObject Read & WriteAll buckets, or only the ones you pick
See every bucket and its settings, and read filesAdmin Read onlyEvery bucket in the workspace
Do everything, including create and delete bucketsAdmin Read & WriteEvery bucket in the workspace

A credential limited to bucket A can’t read or write bucket B. For an app that uses one bucket, create an Object credential for just that bucket.

Before you begin

  • A workspace with at least one bucket. See Create a bucket.
  • Access to Organization → API Tokens in the portal.
  • For organizations billed in India: a verified payment method and, if the ₹1 was your only payment, a first top-up of at least ₹500. Until then the S3 credentials tab shows Verify payment method or Top up ₹500 in place of the create button. See Verify a payment method.
  • The tool you will use: the AWS CLI version 2, rclone, or an S3 SDK.

Create a credential

1

Open S3 Credentials

In the portal sidebar, open Organization → API Tokens, then the S3 Credentials tab. (The S3 API Credentials button on the Object Storage page opens the same tab.)

2

Fill in the form

Click Create S3 Credential. Enter a name that says what uses it (for example backup-server), choose the workspace, and choose the permission level. For an Object level, under Specify bucket(s), choose Apply to all buckets in this organization (including newly created buckets) or Apply to specific buckets only and pick the buckets.

3

Copy the keys

Click Create Credential. The dialog shows the Access Key ID, the Secret Access Key and the S3 Endpoint. Copy all three now.

The Secret Access Key is shown once only. If you lose it, you can’t see it again: revoke the credential and create a new one.

The first credential in a workspace also sets up the workspace’s S3 endpoint. A brand-new endpoint can take a few minutes to start answering.

The three settings every tool needs

SettingValue
Endpointhttps://WORKSPACE-ID.blob.ibeestorage.com — shown as S3 Endpoint when you create the credential
Regionauto
Addressing stylepath (the bucket name goes in the path, not the hostname)

Tools that use us-east-1 as their default region make requests that fail with Invalid region scope, so always set the region to auto.

AWS CLI

Save the credential as a profile named ibee:

aws configure set aws_access_key_id YOUR-ACCESS-KEY-ID --profile ibee
aws configure set aws_secret_access_key YOUR-SECRET-ACCESS-KEY --profile ibee
aws configure set region auto --profile ibee
aws configure set s3.addressing_style path --profile ibee

Then pass the endpoint and profile with each command:

# List your buckets
aws s3 ls --endpoint-url https://WORKSPACE-ID.blob.ibeestorage.com --profile ibee
# Upload a file
aws s3 cp ./report.pdf s3://my-bucket/reports/report.pdf \
--endpoint-url https://WORKSPACE-ID.blob.ibeestorage.com --profile ibee

rclone

Add this to your rclone config (rclone config file shows where it is):

[ibee]
type = s3
provider = Other
access_key_id = YOUR-ACCESS-KEY-ID
secret_access_key = YOUR-SECRET-ACCESS-KEY
endpoint = https://WORKSPACE-ID.blob.ibeestorage.com
region = auto
force_path_style = true

Test it with rclone lsd ibee:, which lists your buckets.

SDKs

Set the same three values in the client. For example, in Python (boto3):

import boto3
from botocore.config import Config
s3 = boto3.client(
"s3",
endpoint_url="https://WORKSPACE-ID.blob.ibeestorage.com",
aws_access_key_id="YOUR-ACCESS-KEY-ID",
aws_secret_access_key="YOUR-SECRET-ACCESS-KEY",
region_name="auto",
config=Config(signature_version="s3v4", s3={"addressing_style": "path"}),
)
print(s3.list_buckets()["Buckets"])

In Node.js (AWS SDK v3), use region: "auto" and forcePathStyle: true.

Manage credentials

The S3 Credentials tab lists credentials from every workspace you can access; use the workspace filter to show one. Each row shows Access (the workspace), Permissions, Created, Last Used and Status (Active or Revoked).

  • Revoke stops a credential working immediately, including every presigned URL it signed. The row stays in the list as Revoked. This can’t be undone.
  • Delete removes a revoked credential from the list. Click Delete permanently to confirm.

To rotate a credential (replace its keys without downtime): create a new credential, update your apps to use it, check that Last Used shows the new one in use, then revoke the old one.

In the public API, credentials are per workspace: GET /object-storage/credentials, POST /object-storage/credentials (name, permission_type, bucket_scope, allowed_buckets), GET /object-storage/credentials/{access_key_id}, and DELETE /object-storage/credentials/{access_key_id} to stop a credential working.

Limits and timing

Value
Secret Access KeyShown once, when the credential is created
Workspaces per credential1
Permission levels per credential1 (it can’t be changed later: create a new credential instead)
New workspace endpointSet up when the workspace’s first credential is created; it can take a few minutes to answer
RevokingTakes effect immediately, including for presigned URLs the credential signed
Clock tolerance15 minutes between your computer’s clock and the service

Troubleshooting

You seeWhat to do
403 AccessDenied — Invalid region scopeSet the region to auto.
Verify payment method instead of the create buttonPay ₹1 to verify your organization’s payment method. See Verify a payment method.
Top up ₹500, with Top up ₹500 to create S3 access keys.Your organization is verified by the ₹1 alone. Top up at least ₹500, then create the credential.
403 AccessDenied — Invalid access key or Access key is not activeThe credential was revoked or deleted, or the key was mistyped. Use an active credential.
403 AccessDenied — Access key does not belong to this workspaceUse the endpoint of the credential’s own workspace.
403 AccessDenied on one bucket or one actionThe credential’s permission level or bucket list doesn’t include it. Create a credential with the right level.
403 SignatureDoesNotMatchThe Secret Access Key is wrong. Check for missing characters or extra spaces.
403 AccessDenied — Request has expiredThe computer’s clock is more than 15 minutes off. Sync it and try again.
”Could not resolve host” for my-bucket.WORKSPACE-ID.blob.ibeestorage.comSet the addressing style to path.