Hubble Network API Keys API

openapi: 3.2.0
info:
  title: Hubble Platform API Keys API
  description: The Hubble platform is built API-first.
  version: 1.0.0
servers:
- url: https://api.hubble.com
  description: Production
security:
- BearerAuth: []
tags:
- name: API Keys
paths:
  /v1/org/{org_id}/check:
    get:
      tags:
      - API Keys
      operationId: validate-api-key
      x-criticality: high
      summary: Validate an API Key
      description: Confirm your API key is valid.
      parameters:
      - $ref: '#/components/parameters/orgIdPathParam'
      responses:
        '200':
          description: API key validated
          content:
            application/json:
              schema:
                type: object
                properties:
                  org_id:
                    $ref: '#/components/schemas/orgId'
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '500':
          $ref: '#/components/responses/ErrorInternalServer'
  /v1/org/{org_id}/key:
    post:
      tags:
      - API Keys
      operationId: provision-api-key
      x-criticality: high
      summary: Provision an API Key
      description: 'Provision a new API Key for your organization.


        **Required Scope:** `write-api-keys`


        ### Authorization Scopes

        API Keys can be created with specific authorization scopes that control what operations the key can perform.

        If no scopes are specified, the key will be created with all available scopes (admin-level access).

        See the Cloud API "Introduction" for a complete list authorization scopes.


        ### Expiration Date

        Set an appropriate expiration date for temporary API access. For no expiration, set to `0`.'
      parameters:
      - $ref: '#/components/parameters/orgIdPathParam'
      - $ref: '#/components/parameters/contentTypeJsonHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  $ref: '#/components/schemas/apiKeyName'
                expires_at_seconds:
                  $ref: '#/components/schemas/apiKeyExpiration'
                scopes:
                  $ref: '#/components/schemas/authScope'
                  example:
                  - read-api-keys
                  - read-users
                  - read-devices
      responses:
        '200':
          description: API key provisioned
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/apiKeyItem'
                - type: object
                  properties:
                    key:
                      $ref: '#/components/schemas/apiKey'
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '500':
          $ref: '#/components/responses/ErrorInternalServer'
    get:
      tags:
      - API Keys
      operationId: list-api-keys
      x-criticality: high
      summary: List all API Keys
      description: 'List all valid API Keys for your organization.


        **Required Scope:** `read-api-keys`'
      parameters:
      - $ref: '#/components/parameters/orgIdPathParam'
      responses:
        '200':
          description: List of API keys
          content:
            application/json:
              schema:
                type: object
                properties:
                  keys:
                    type: array
                    items:
                      $ref: '#/components/schemas/apiKeyItem'
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '500':
          $ref: '#/components/responses/ErrorInternalServer'
  /v1/org/{org_id}/key/{key_id}:
    delete:
      tags:
      - API Keys
      operationId: delete-api-key
      x-criticality: high
      summary: Delete an API Key
      description: 'Permanently delete an API Key from your organization.


        **Required Scope:** `write-api-keys`'
      parameters:
      - $ref: '#/components/parameters/orgIdPathParam'
      - name: key_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/apiKeyId'
        description: API key ID
      responses:
        '200':
          description: API key deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  key_id:
                    $ref: '#/components/schemas/apiKeyId'
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '500':
          $ref: '#/components/responses/ErrorInternalServer'
    patch:
      tags:
      - API Keys
      operationId: update-api-key
      x-criticality: high
      summary: Update an API Key
      description: 'Update metadata for an API key, including name, authorization scopes, and expiration time.


        **Required Scope:** `write-api-keys`


        ### Authorization Scopes

        You may update the scopes assigned to an API key to change its permissions. See the Cloud API "Introduction" for a complete list authorization scopes.


        ### Expiration Time

        You may update the expiration time for an API key. Set to 0 to remove expiration (key will never expire).'
      parameters:
      - $ref: '#/components/parameters/orgIdPathParam'
      - name: key_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/apiKeyId'
        description: API key ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                set_name:
                  $ref: '#/components/schemas/apiKeyName'
                set_scopes:
                  $ref: '#/components/schemas/authScope'
                  example:
                  - read-api-keys
                  - read-users
                  - read-devices
                set_expires_at_seconds:
                  $ref: '#/components/schemas/apiKeyExpiration'
      responses:
        '200':
          description: API Key Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiKeyItem'
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '500':
          $ref: '#/components/responses/ErrorInternalServer'
  /v1/org/{org_id}/key_scopes:
    get:
      tags:
      - API Keys
      operationId: list-key-scopes
      x-criticality: high
      summary: List Key Scopes
      description: 'Retrieve a list of all available authorization scopes that can be assigned to API keys.

        This endpoint returns scope IDs and human-readable display names.


        **Required Scope:** `read-api-keys`'
      parameters:
      - $ref: '#/components/parameters/orgIdPathParam'
      responses:
        '200':
          description: List of available scopes
          content:
            application/json:
              schema:
                type: object
                properties:
                  scopes:
                    type: array
                    items:
                      type: object
                      properties:
                        scope_id:
                          $ref: '#/components/schemas/authScope'
                          description: The scope identifier used in API requests
                        display_name:
                          type: string
                          description: Human-readable name for the scope
                      required:
                      - scope_id
                      - display_name
                    description: List of all available authorization scopes
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '500':
          $ref: '#/components/responses/ErrorInternalServer'
components:
  schemas:
    apiKeyName:
      type: string
      description: A name for an API Key
      maxLength: 250
    authScope:
      type: string
      enum:
      - read-api-keys
      - write-api-keys
      - read-users
      - write-users
      - read-organization-metadata
      - write-organization-metadata
      - read-devices
      - write-devices
      - read-invitations
      - write-invitations
      - read-packets
      - read-platform-metrics
      - read-billing-usage
      - read-billing-invoices
      - read-webhooks
      - write-webhooks
      description: Authorization scope for API key permissions
    apiKey:
      type: string
      description: An API key
    apiKeyExpiration:
      type: integer
      format: int64
      description: 'An UTC second-precision timestamp formatted as an integer.

        Can be set to 0 to indicate that there is no expiration.

        '
    apiKeyId:
      type: string
      description: An ID for an API key
    errorResponse:
      type: object
      properties:
        code:
          type: integer
          description: The HTTP status code
        description:
          type: string
          description: 'A description for the error.

            For user errors, we attempt to be as descriptive as possible to help with diagnosing the issue.

            For internal errors, the error description is only indicates that a retry should occur but we log the full error so that we can diagnose it.

            Error descriptions can change over time and should not be programmed against.

            '
        name:
          type: string
          enum:
          - Bad Request
          - Unauthorized
          - Not Found
          - Too Many Requests
          - Internal Server Error
          description: '`name` is a short name for the error.

            '
    orgId:
      type: string
      format: uuid
      description: The ID for an organization
    utcTimestampInteger:
      type: integer
      format: int64
      description: An UTC second-precision timestamp formatted as an integer
    apiKeyItem:
      type: object
      description: An API Token used to authenticate with the Hubble Platform
      properties:
        key_id:
          $ref: '#/components/schemas/apiKeyId'
        key_name:
          $ref: '#/components/schemas/apiKeyId'
        created_at:
          $ref: '#/components/schemas/utcTimestampInteger'
        expires_at_seconds:
          $ref: '#/components/schemas/apiKeyExpiration'
        scopes:
          type: array
          items:
            $ref: '#/components/schemas/authScope'
          description: List of authorization scopes assigned to this API key
  responses:
    ErrorInternalServer:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            code: 500
            description: An unknown error has occurred.
            name: Unknown
    ErrorBadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            code: 400
            description: The request could not be understood by the server due to malformed syntax.
            name: Bad Request
  parameters:
    orgIdPathParam:
      name: org_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/orgId'
      description: Your organization ID
    contentTypeJsonHeader:
      name: Content-Type
      in: header
      schema:
        type: string
      description: An indication that the payload is JSON
      example: application/json
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT