IAM-STS API

The Backblaze IAM and STS API provides AWS-compatible identity and access management operations for Backblaze B2 Cloud Storage. It is designed for customers and platform developers that use AWS-compatible tools, SDKs, and automation to manage identities, permissions, access keys, and temporary credentials.

Availability

IAM and STS operations are being made available in phases. See the IAM and STS API Reference for operation-specific availability.

The IAM and STS API enables you to automate the following processes:

• Create, list, and delete IAM users and roles

• Add, list, and delete inline policies for users and roles

• Create, list, activate, deactivate, and delete IAM access keys

• Generate temporary credentials by assuming IAM roles or exchanging OIDC identity tokens

• Retrieve information about the identity associated with a set of credentials

• Create, retrieve, and delete bucket policies

• Register OIDC identity providers and configure IAM roles that trust them

Backblaze IAM supports a subset of AWS IAM and STS functionality, including user and role management, inline policies, access key lifecycle management, role assumption, OIDC workload identity federation, and bucket policies.

For all IAM and STS API operations and their corresponding documentation, see the IAM and STS API Reference.

AWS Compatibility

Backblaze IAM and STS use the AWS Query API protocol. Most operations require AWS Signature Version 4 (SigV4) authentication. The AssumeRoleWithWebIdentity operation uses an OIDC JSON Web Token (JWT) for authentication instead of SigV4. Requests use application/x-www-form-urlencoded parameters, and responses use AWS-compatible XML. These conventions allow AWS-compatible tools and SDKs to work with Backblaze when configured to use the appropriate Backblaze endpoint.

Backblaze IAM intentionally supports a subset of AWS IAM and STS functionality. The following features are not currently supported:

• Managed policies

• Policy attachments

• Permissions boundaries

• Resource tagging on IAM resources or S3/B2 buckets

• Regional STS endpoints

Policies are supported as inline user policies, inline role policies, session policies supplied with AssumeRole, and bucket policies.

Authentication

IAM and STS requests require AWS Signature Version 4 (SigV4) authentication, except for AssumeRoleWithWebIdentity.

The AssumeRoleWithWebIdentity operation authenticates requests using an OIDC JWT instead of SigV4. Do not include an IAM authorization header when exchanging a JWT for temporary credentials.

When you use temporary STS credentials to sign subsequent requests, include the session token in the X-Amz-Security-Token header.

Use the following service endpoints:

IAM: https://iam.backblazeb2.com/
STS: https://sts.backblazeb2.com/

IAM operations use API version 2010-05-08, and STS operations use API version 2011-06-15. All operations support POST. Some read-only operations also support GET, but POST is the recommended method.

IAM Users and Roles

IAM users and roles are identities that can be granted access to resources in a Backblaze account.

Use IAM user operations to create, list, and delete users. Users can have inline policies and access keys that authorize supported IAM and S3-compatible operations.

Use IAM roles for workloads that need permissions that can be assumed temporarily. Each role includes a trust policy that controls which principals can assume the role. Roles can also have inline policies that define the permissions available to role sessions.

Policies

Backblaze IAM uses AWS-compatible JSON policy documents to control access.

Policies are supported as:

• Inline policies attached to IAM users

• Inline policies attached to IAM roles

• Session policies supplied with AssumeRole

• Bucket policies

• Role trust policies

Backblaze IAM supports AWS-compatible policy elements, condition operators, condition keys, and policy variables. Support varies by policy type and request context. For a complete list of supported features and limitations, see Supported IAM Policy Elements and Conditions.

Access Keys

IAM access keys provide long-lived credentials for IAM users. An access key consists of an access key ID and a secret access key.

The secret access key is returned only when the key is created and cannot be retrieved later. Each IAM user can have up to two access keys. Access keys can be set to Active or Inactive without deleting them. 

For workloads that do not require persistent credentials, use temporary STS credentials instead of long-lived access keys.

Temporary Credentials with STS

Use the Backblaze STS API to create temporary AWS-compatible credentials for an IAM role.

The AssumeRole operation returns an access key ID, secret access key, session token, and expiration time for a role session. A session can also include an inline session policy that further restricts the permissions available to the session.

Supported session durations range from 900 seconds to 43,200 seconds, or 15 minutes to 12 hours.

Use GetCallerIdentity to retrieve the account and principal associated with the credentials used for a request.

OIDC Workload Identity Federation

Backblaze STS supports AssumeRoleWithWebIdentity, which allows workloads to exchange OIDC identity tokens for temporary IAM credentials without storing long-lived access keys.

An administrator registers an OIDC identity provider and creates an IAM role with a trust policy that authorizes the workload. Backblaze validates the token and evaluates the trust policy before issuing temporary credentials.

For more information, see OIDC Workload Identity with Backblaze IAM and Configure OIDC Workload Identity.

STS Session Behavior

An STS session is associated with an IAM role. When temporary credentials are used, Backblaze evaluates the current identity policies associated with that role. Changes to existing role policies, or policies added to the role, can therefore affect existing sessions after normal policy propagation delays.

A session policy supplied with AssumeRole is fixed for the lifetime of the session. A session policy cannot grant permissions beyond those available to the role; it can only further restrict the permissions available to the session.

Updating the identity policies associated with a role can be used to restrict or revoke access for existing sessions. These changes are subject to the normal eventual-consistency behavior of Backblaze IAM.

Bucket Policies

Bucket policies provide resource-based access control for B2 buckets through the S3-compatible API.

Use the S3-compatible PutBucketPolicy, GetBucketPolicy, and DeleteBucketPolicy operations to manage bucket policies. Requests must be sent to the S3-compatible endpoint for the region that contains the bucket.

Bucket policies use AWS-compatible JSON policy documents and can grant or restrict access for supported IAM principals.

Request and Response Behavior

IAM and STS operations follow AWS Query API conventions:

• Requests use AWS Signature Version 4 authentication, except for AssumeRoleWithWebIdentity, which authenticates using an OIDC JWT

• Request parameters are sent using application/x-www-form-urlencoded.

• POST is supported for all IAM and STS operations.

• Responses are returned as XML.

• Error responses use AWS-compatible error codes and include a request ID that can be used for troubleshooting.

Consistency

Backblaze IAM is eventually consistent. Changes to users, roles, policies, access keys, and bucket policies may take a short amount of time to propagate. For example, a newly created role might not be immediately available to AssumeRole, or a new or updated policy might not take effect immediately.

Applications and automated workflows should account for brief propagation delays when making requests immediately after creating or modifying IAM resources.

Limits and Quotas

Policy size limits are applied after URL decoding.