Introduction

Availability

Early Access: July 30, 2026
Early Access is gated; contact the Backblaze Sales team for access.

Limited Availability: September 30, 2026
Limited Availability is available only to customers with access to the Backblaze Enterprise Web Console. For more information, contact the Backblaze Sales team.

The Public Organizations API provides account-lifecycle and identity control-plane functionality, including Organizational Unit and account provisioning, Service Principal metadata and key management, access restrictions, and short-lived AWS-compatible credential issuance.

Using the Public Organizations API, you can:

• Create, list, update, move, delete, undelete, suspend, and unsuspend accounts

• Create, list, update, and delete Organizational Units under an organization

• Retrieve metadata for Service Principals scoped to an account

• Create, list, update, delete, disable, and enable Service Principal Keys

• Configure per-Service-Principal source IP allowlists using Access Restrictions

• Generate short-lived AWS-compatible credentials for IAM roles in an account

Availability varies by operation. See the availability information for each API operation for details.

Prerequisites

To get started, you need a Backblaze organization with at least one active Service Principal Key.

Service Principals are created and managed using the Backblaze Enterprise Web Console. The Public Organizations API lets you retrieve Service Principal information and manage Service Principal Keys.

Authentication

The Public Organizations API uses short-lived bearer tokens minted from long-lived Service Principal Key credentials. Clients exchange a credentialId and secret for a bearer token by calling GET /orgs/v1/authorize using HTTP Basic authentication. All other endpoints require the returned token in the Authorization header:

Authorization: Bearer {authToken}

Bearer tokens remain usable only while the backing Service Principal remains active. If the Service Principal is deleted, disabled, or otherwise revoked, calls made using tokens minted from its keys fail authorization.

Disabling or deleting a Service Principal Key prevents the key from minting new bearer tokens. Bearer tokens that were already issued remain valid until they expire, unless the backing Service Principal is revoked.

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

API Base URL

The base URL for Public Organizations API operations is:

https://api.backblazeb2.com

Request and Response Formats

The following request and response conventions apply to the Public Organizations API.

Status Codes

For all calls to the Public Organizations API, the returned HTTP status code indicates success or failure. Successful calls generally return 200 OK; deletion operations return 204 No Content. Responses in the 400 and 500 ranges indicate failures. The API does not currently use redirects.

Error Structure

Every response includes a Request-Id HTTP header. Error responses also include a top-level requestId in the JSON response body that matches the header.

The response also includes an error object containing:

• code — A numeric code that identifies the error condition.

• message — A human-readable description of the error.

• details — Structured, non-sensitive diagnostic information related to the error condition.

Include the requestId value when contacting Backblaze Support so the request can be correlated with server-side traces.

HTTP Status Codes

JSON Error Structure

The following example shows a JSON error response:

{
    "requestId": "4bf92f3577b34da6a3ce929d0e0e4736",
    "error": {
        "code": 10,
        "message": "etag mismatch",
        "details": {}
    }
}

API Versions

The current version is v1.

Rate Limits

The Public Organizations API is rate limited by both source IP address and global account ID.

The default limits are:

• Source IP address: 100 requests per second

• Account ID: 100 requests per second

• Account ID: 6,000 requests per minute

The account-level request allowance is shared by all Service Principals operating under the same account. If multiple Service Principals are active simultaneously, their combined requests count against the same account-level limits.

Requests that exceed a limit return 429 TOO_MANY_REQUESTS. Use exponential backoff when retrying.

Authorization Consistency

Authorization changes are eventually consistent. Creating a resource or changing role bindings or permissions can briefly result in requests being evaluated against an earlier authorization state.

For example, immediately accessing an account after creating it can temporarily return 403 FORBIDDEN while the caller's authorization for the new resource propagates.

Clients that perform an operation immediately after a write should retry unexpected 403 FORBIDDEN responses with exponential backoff.

Concurrency and updateMask

Resources include an opaque etag that changes whenever the resource's contents change. Supplying the etag in a PATCH request makes the update conditional and atomic. If the supplied etag does not match the current resource, the request returns 409 CONFLICT.

PATCH operations support partial updates using the updateMask query parameter. If updateMask is omitted, the server updates all mutable fields present in the request body. If updateMask is provided, the server updates only the fields specified in the mask.