Organizations API

The Backblaze Organizations API enables you to programmatically create, manage, and access multiple Backblaze B2 Cloud Storage accounts within an organization. It is designed for enterprise customers, service providers, and platform developers that need to automate account provisioning, organization structure, and server-to-server access.

The Organizations API enables you to automate the following processes:

• Create, list, update, move, delete, and recover accounts

• Retrieve service principal information and manage service principal keys

• Restrict service principal authentication to approved source IP addresses

• Generate short-lived, AWS-compatible credentials for IAM roles

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

Organizations and Accounts

An organization is the top-level administrative boundary for a collection of Backblaze B2 Cloud Storage accounts.

An account is the primary security and isolation boundary for storage, IAM, credentials, and lifecycle operations. Every account must be associated with a billing account in the same organization. Multiple accounts can share one billing account.

The API returns stable REST-like resource names for accounts, service principals, and keys, such as accounts/123456789012. Accounts use 12-digit numeric identifiers.

Authentication

Organizations API requests are authenticated by a service principal. Service principals are non-human identities that are created and managed in the Enterprise Web Console. The Organizations API lets you retrieve service principal information and manage service principal keys.

Each service principal belongs to an account, which serves as its administrative home. The roles assigned to the service principal determine which resources it can access, including resources in other accounts.

To authenticate, exchange the credential ID and secret of a service principal key for a short-lived bearer token by calling the authorization endpoint with HTTP Basic authentication:

GET https://api.backblazeb2.com/orgs/v1/authorize
Authorization: Basic base64(credentialId:secret)

The response includes an authToken. Include the token with subsequent requests:

Authorization: Bearer {authToken}

The default token duration is one hour, and the requested duration cannot exceed 12 hours. The actual duration is limited by the remaining lifetime of the service principal key.

The Organizations API does not use AWS Signature Version 4 credentials. AWS-compatible access keys, secret access keys, and session tokens are used with the Backblaze IAM, STS, and S3 APIs.

Service Principals and Keys

Use the Organizations API to retrieve service principal information and manage service principal keys. A service principal key is a long-lived credential associated with a service principal.

You can create, list, retrieve, rename, disable, enable, and delete service principal keys.

• The secret is returned only when the key is created and cannot be retrieved later.

• A key can have an absolute expiration time or a time to live. If neither is supplied, the key does not expire.

• Disabling or deleting a key prevents it from minting new bearer tokens.

• Bearer tokens that were already issued remain valid until they expire, unless the backing service principal is revoked.

Access Restrictions

You can configure a source IP allowlist for each service principal. Allowlist entries can be individual IPv4 or IPv6 addresses or CIDR ranges. Responses normalize entries to canonical CIDR notation.

When enforcement is disabled, the allowlist is retained but is not applied. When enforcement is enabled, authentication succeeds only from an allowed address. Enabling enforcement with an empty allowlist denies all authentication requests for that service principal.

Account Management

Use account operations to model tenants, applications, departments, or environments within an organization for access-control purposes.

Account provisioning is asynchronous. New accounts are usable within minutes after a successful create request returns.

Account updates support partial changes. Moving an account changes its placement within the organization without changing its account identifier, IAM principals, or data-plane configuration. Deleting an account starts a retention window during which the account may be restored before it is purged.

See the operation-level availability information in the API reference before designing a workflow.

Temporary IAM Role Credentials

The GenerateIamRoleCredentials operation returns short-lived AWS-compatible credentials for an IAM role in a target account. The response includes an access key ID, secret access key, session token, and expiration time.

Use these credentials with supported Backblaze IAM, STS, and S3 operations. The default session duration is one hour; supported durations range from 15 minutes to 12 hours. When the credentials expire, call the operation again to generate a new credential set.

Request and Response Behavior

• The API uses REST and JSON over HTTPS.

• Mutable resources include an opaque etag for conditional, atomic updates.

• PATCH requests support an optional updateMask for partial updates.

• List operations use pageSize and opaque pageToken values for pagination.

• Every response includes a Request-Id header. Include this value when you contact Backblaze Support about a request.

• The API returns 429 TOO_MANY_REQUESTS when a rate limit is exceeded. Retry with exponential backoff.