openapi: 3.0.3
info:
  title: Backblaze B2 Native Application Keys Authorization API
  description: The Backblaze B2 Native API provides programmatic access to Backblaze B2 Cloud Storage. It covers account authorization, bucket management, file upload and download, lifecycle rules, application key management, large file handling, replication, and event notifications. The API uses HTTPS with JSON request and response bodies. Authentication is performed via the b2_authorize_account endpoint which returns an authorization token used for subsequent calls.
  version: v4
  x-generated-from: documentation
  contact:
    name: Backblaze Developer Support
    url: https://www.backblaze.com/docs
  license:
    name: Proprietary
    url: https://www.backblaze.com/company/terms-of-service
servers:
- url: https://api.backblazeb2.com
  description: Backblaze B2 API (cluster-specific URL returned by b2_authorize_account)
security:
- ApplicationKeyAuth: []
tags:
- name: Authorization
  description: Account authorization and token management
paths:
  /b2api/v4/b2_authorize_account:
    get:
      operationId: authorizeAccount
      summary: Backblaze B2 Native API Authorize Account
      description: Used to log in to the B2 API. Returns an authorization token that can be used for account-level operations. The authorization token is valid for at most 24 hours. This endpoint uses HTTP Basic authentication with the application key ID as the username and the application key as the password.
      tags:
      - Authorization
      security:
      - BasicAuth: []
      responses:
        '200':
          description: Successful authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizeAccountResponse'
              examples:
                AuthorizeAccount200Example:
                  summary: Default authorizeAccount 200 response
                  x-microcks-default: true
                  value:
                    accountId: abc123def456
                    authorizationToken: 4_002acd2a08df7f8c0c4d21e9deef28c7
                    allowed:
                      capabilities:
                      - listKeys
                      - writeKeys
                      - deleteKeys
                      - listBuckets
                      - readBuckets
                      - writeBuckets
                      - deleteBuckets
                      - listFiles
                      - readFiles
                      - shareFiles
                      - writeFiles
                      - deleteFiles
                      bucketId: null
                      bucketName: null
                      namePrefix: null
                    apiInfo:
                      storageApi:
                        absoluteMinimumPartSize: 5000000
                        recommendedPartSize: 100000000
                        apiUrl: https://api005.backblazeb2.com
                        downloadUrl: https://f005.backblazeb2.com
                        s3ApiUrl: https://s3.us-west-004.backblazeb2.com
        '401':
          description: Unauthorized - invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /b2api/v4/b2_get_download_authorization:
    post:
      operationId: getDownloadAuthorization
      summary: Backblaze B2 Native API Get Download Authorization
      description: Used to generate an authorization token that can be used to download files with the specified prefix from a private bucket.
      tags:
      - Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetDownloadAuthorizationRequest'
            examples:
              GetDownloadAuthorizationRequestExample:
                summary: Default getDownloadAuthorization request
                x-microcks-default: true
                value:
                  bucketId: e73ede9969c64355ef8b
                  fileNamePrefix: photos/
                  validDurationInSeconds: 3600
      responses:
        '200':
          description: Download authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDownloadAuthorizationResponse'
              examples:
                GetDownloadAuthorization200Example:
                  summary: Default getDownloadAuthorization 200 response
                  x-microcks-default: true
                  value:
                    bucketId: e73ede9969c64355ef8b
                    fileNamePrefix: photos/
                    authorizationToken: 3_en0Y0j2f-0r0BVLS8vN9GJTWA-pLEP
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    GetDownloadAuthorizationRequest:
      title: GetDownloadAuthorizationRequest
      type: object
      required:
      - bucketId
      - fileNamePrefix
      - validDurationInSeconds
      properties:
        bucketId:
          type: string
          description: Bucket to authorize downloads from
          example: e73ede9969c64355ef8b
        fileNamePrefix:
          type: string
          description: Files must have this name prefix
          example: photos/
        validDurationInSeconds:
          type: integer
          description: Duration (1 to 604800) the token is valid
          example: 3600
    ApiInfo:
      title: ApiInfo
      type: object
      description: API endpoint information
      properties:
        storageApi:
          type: object
          properties:
            absoluteMinimumPartSize:
              type: integer
              description: Minimum part size in bytes for large files
              example: 5000000
            recommendedPartSize:
              type: integer
              description: Recommended part size in bytes
              example: 100000000
            apiUrl:
              type: string
              description: URL to use for subsequent API calls
              example: https://api005.backblazeb2.com
            downloadUrl:
              type: string
              description: URL to use for downloading files
              example: https://f005.backblazeb2.com
            s3ApiUrl:
              type: string
              description: S3-compatible API URL
              example: https://s3.us-west-004.backblazeb2.com
    AuthorizeAccountResponse:
      title: AuthorizeAccountResponse
      type: object
      description: Response from the b2_authorize_account operation
      properties:
        accountId:
          type: string
          description: The identifier for the account
          example: abc123def456
        authorizationToken:
          type: string
          description: An authorization token to use with all calls other than b2_authorize_account
          example: 4_002acd2a08df7f8c0c4d21e9deef28c7
        allowed:
          $ref: '#/components/schemas/AllowedCapabilities'
        apiInfo:
          $ref: '#/components/schemas/ApiInfo'
    GetDownloadAuthorizationResponse:
      title: GetDownloadAuthorizationResponse
      type: object
      properties:
        bucketId:
          type: string
          example: e73ede9969c64355ef8b
        fileNamePrefix:
          type: string
          example: photos/
        authorizationToken:
          type: string
          example: 3_en0Y0j2f-0r0BVLS8vN9GJTWA-pLEP
    ErrorResponse:
      title: ErrorResponse
      type: object
      description: Standard B2 error response
      properties:
        status:
          type: integer
          description: HTTP status code
          example: 401
        code:
          type: string
          description: A single-identifier code that identifies the error
          example: unauthorized
        message:
          type: string
          description: A human-readable message describing the error
          example: Authorization token not valid
    AllowedCapabilities:
      title: AllowedCapabilities
      type: object
      description: What the credentials allow
      properties:
        capabilities:
          type: array
          items:
            type: string
          description: A list of capabilities
        bucketId:
          type: string
          nullable: true
          description: Bucket ID restricted to, or null
        bucketName:
          type: string
          nullable: true
          description: Bucket name restricted to, or null
        namePrefix:
          type: string
          nullable: true
          description: File name prefix restriction, or null
  securitySchemes:
    ApplicationKeyAuth:
      type: http
      scheme: bearer
      description: Authorization token obtained from b2_authorize_account
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic auth using applicationKeyId as username and applicationKey as password