Fly.io Extensions API

openapi: 3.1.0
info:
  title: Fly.io Apps Extensions API
  description: The Fly.io Extensions API is a provider-facing HTTP interface that enables third-party services to integrate with the Fly.io platform as extension providers. When a Fly.io user provisions an extension via the flyctl CLI, Fly.io forwards the provisioning request to the provider's API with details about the requesting organization and user, and the provider responds with environment variable configuration that is attached to the target application. Providers must also support single sign-on login flows using OAuth, daily billing detail endpoints, and webhook delivery for resource lifecycle events. Extensions currently available through this program include Sentry, Supabase, Tigris object storage, Upstash Redis and Vector, and others.
  version: '1.0'
  contact:
    name: Fly.io Extensions Program
    url: https://fly.io/docs/reference/extensions_api/
  termsOfService: https://fly.io/legal/terms-of-service/
servers:
- url: https://{provider_base_url}
  description: Provider-hosted API server. Each extension provider hosts their own implementation of this API at a URL they register with Fly.io.
  variables:
    provider_base_url:
      default: api.example.com
      description: The base URL registered by the extension provider with Fly.io.
- url: https://api.fly.io
  description: Fly.io platform server for OAuth and webhook endpoints.
security:
- flySharedSecret: []
tags:
- name: Extensions
  description: Operations for provisioning, retrieving, and updating extension resource instances. Fly.io calls these endpoints on the provider's server when users interact with extensions via the flyctl CLI.
paths:
  /extensions:
    post:
      operationId: provisionExtension
      summary: Provision an extension resource
      description: Called by Fly.io when a user provisions an extension via the flyctl CLI. The provider must create the requested resource and respond with its unique ID and a config object containing the environment variables to inject into the user's Fly App. Provisioning must complete within 5 seconds; if the resource takes longer to create, the provider should respond immediately and use the webhook endpoint to notify Fly.io when the resource becomes available.
      tags:
      - Extensions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProvisionRequest'
      responses:
        '200':
          description: Extension provisioned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvisionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /extensions/{extension_id}:
    get:
      operationId: getExtension
      summary: Get extension resource details
      description: Called by Fly.io to fetch the current status and usage information for a specific extension resource. This endpoint is used for polling when an extension is provisioned asynchronously and takes longer than 5 seconds to become ready.
      tags:
      - Extensions
      parameters:
      - $ref: '#/components/parameters/extensionId'
      responses:
        '200':
          description: Extension resource details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtensionResource'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateExtension
      summary: Update an extension resource
      description: Called by Fly.io when a user updates the configuration of an extension resource, such as changing the region or plan. The provider applies the updated configuration and returns the updated resource details.
      tags:
      - Extensions
      parameters:
      - $ref: '#/components/parameters/extensionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProvisionRequest'
      responses:
        '200':
          description: Extension updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvisionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteExtension
      summary: Delete an extension resource
      description: Called by Fly.io when a user removes an extension from their app. The provider should clean up all resources associated with this extension instance and remove the user's environment variables.
      tags:
      - Extensions
      parameters:
      - $ref: '#/components/parameters/extensionId'
      responses:
        '200':
          description: Extension deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    ExtensionResource:
      type: object
      description: Full details about a provisioned extension resource.
      properties:
        id:
          type: string
          description: Unique identifier for this extension resource.
        name:
          type: string
          description: Human-readable name for the resource.
        status:
          type: string
          description: Current status of the resource (e.g., pending, ready, error).
          enum:
          - pending
          - ready
          - error
        config:
          type: object
          description: Current environment variable configuration for the resource.
          additionalProperties:
            type: string
    ProvisionRequest:
      type: object
      description: Request body sent by Fly.io to the provider when provisioning or updating an extension resource.
      required:
      - name
      - id
      - organization_id
      - organization_name
      - user_email
      - user_id
      - user_role
      properties:
        name:
          type: string
          description: The name the user specified for this extension resource.
        id:
          type: string
          description: Fly.io-generated unique identifier for this extension instance.
        organization_id:
          type: string
          description: The Fly.io organization ID of the user provisioning the extension.
        organization_name:
          type: string
          description: The display name of the Fly.io organization.
        user_email:
          type: string
          format: email
          description: An obfuscated email alias for the provisioning user. This is a routing address that Fly.io manages, not the user's real email.
        user_id:
          type: string
          description: The Fly.io user ID of the provisioning user.
        user_role:
          type: string
          description: The user's role within the organization (e.g., admin, member).
        primary_region:
          type: string
          description: The preferred deployment region for latency-sensitive resources.
          example: iad
        read_regions:
          type: array
          description: Additional regions where read replicas should be provisioned.
          items:
            type: string
        ip_address:
          type: string
          description: A Fly.io private IP address allocated for Flycast routing, enabling the extension to receive traffic over the Fly.io private network.
    ErrorResponse:
      type: object
      description: A standard error response.
      properties:
        error:
          type: string
          description: Human-readable error message.
        status:
          type: integer
          description: HTTP status code.
    ProvisionResponse:
      type: object
      description: Response body returned by the provider after successfully provisioning or updating an extension resource.
      required:
      - id
      - config
      properties:
        id:
          type: string
          description: The provider's unique identifier for this extension resource.
        name:
          type: string
          description: Human-readable name for the provisioned resource.
        config:
          type: object
          description: Environment variables to inject into the user's Fly App. Keys are variable names and values are the corresponding secrets or connection strings.
          additionalProperties:
            type: string
        fly_app_name:
          type: string
          description: If the provider runs a Fly App to serve this extension, specify its name here to enable Flycast routing from the customer's private network.
  responses:
    NotFound:
      description: The requested extension resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid authentication credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request parameters or body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    extensionId:
      name: extension_id
      in: path
      description: The unique identifier of the extension resource, as returned by the provider.
      required: true
      schema:
        type: string
  securitySchemes:
    flySharedSecret:
      type: http
      scheme: bearer
      description: Shared secret provided by Fly.io to the extension provider. Fly.io includes this secret in an Authorization Bearer header on all requests to the provider's API for verification.
    oauthBearerAuth:
      type: http
      scheme: bearer
      description: Fly.io OAuth access token obtained from the token exchange endpoint.
    webhookHmac:
      type: apiKey
      in: header
      name: X-Fly-Signature
      description: HMAC-SHA256 signature of the raw request body, computed using the webhook signing secret. Recipients must verify this signature before processing the payload.
externalDocs:
  description: Fly.io Extensions API Documentation
  url: https://fly.io/docs/reference/extensions_api/