Ironfang Rig Connectors API

openapi: 3.2.0
info:
  title: Ironfang Rig Connectors API
  version: 0.1.0
  summary: Disposable inboxes, callback URLs, mock endpoints and connector routes for integration tests.
  description: 'Ironfang Rig gives an application under test a disposable external

    world: temporary inbox addresses, public callback URLs, mock HTTP

    endpoints and connector routes, allocated fresh for every run, with an

    append-only, sequenced timeline of everything Ironfang observed.'
  contact:
    name: Ironfang
    email: hello@ironfang.uk
    url: https://ironfang.com/contact
  termsOfService: https://ironfang.com/legal/terms
  license:
    name: Proprietary - use governed by the Ironfang terms of service
    url: https://ironfang.com/legal/terms
servers:
- url: https://api.ironfang.com/rig
security:
- apiKey: []
- bearerAuth: []
tags:
- name: Connectors
  description: Outbound connectors that forward a run's callbacks to fixed local routes.
paths:
  /v1/runs/{runId}/connectors:
    parameters:
    - $ref: '#/components/parameters/RunId'
    get:
      tags:
      - Connectors
      operationId: listConnectors
      summary: List a run's connectors
      description: Returns every connector minted for the run with its state (pending, online, offline), the routes it is bound to and when it was last seen, plus how many deliveries are still waiting for a connector. Neither credential is ever returned here. Read-only.
      responses:
        '200':
          description: The connectors
          content:
            application/json:
              schema:
                type: object
                required:
                - connectors
                - online
                - pending_deliveries
                properties:
                  connectors:
                    type: array
                    items:
                      $ref: '#/components/schemas/Connector'
                  online:
                    type: integer
                    description: How many connectors hold a session now.
                  pending_deliveries:
                    type: integer
                    description: Callbacks queued for a route that no session has answered yet.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Connectors
      operationId: createConnector
      summary: Mint a connector and its bootstrap token
      description: Mints a connector on an active run and returns its bootstrap token once. The token is single-use, expires after ten minutes, and is bound to this organisation, this run and the route labels named (every label the run declares when none are given). Start `ironfang-connect` with it and a local target for each label; the connector exchanges it at the gateway for a session credential that lives no longer than the run. The platform only ever names a route label; what a label points at is decided on the connector's command line and never leaves the machine. Needs rig.connector. A run may have at most 16 connectors.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  maxLength: 64
                  description: A label for this connector in the timeline, such as the machine it runs on.
                routes:
                  type: array
                  maxItems: 32
                  description: Route labels to bind the credential to; a subset of what the run declares. Default all of them.
                  items:
                    type: string
                    pattern: ^[a-z0-9][a-z0-9-]{0,62}$
      responses:
        '201':
          description: Connector minted; the bootstrap token appears here and nowhere else
          content:
            application/json:
              schema:
                type: object
                required:
                - connector
                - bootstrap_token
                - bootstrap_expires_at
                - gateway_url
                - routes
                - command
                properties:
                  connector:
                    $ref: '#/components/schemas/Connector'
                  bootstrap_token:
                    type: string
                    description: The single-use credential, prefixed `ift_boot_`. Pass it to ironfang-connect in `IRONFANG_CONNECT_TOKEN`.
                  bootstrap_expires_at:
                    type: string
                    format: date-time
                  gateway_url:
                    type: string
                    format: uri
                    description: The WebSocket endpoint the connector dials.
                  routes:
                    type: array
                    items:
                      type: string
                  command:
                    type: string
                    description: The command line to complete with local targets.
                  release:
                    type: object
                    description: The ironfang-connect build to run, when the API knows it.
                    required:
                    - version
                    - checksums_url
                    properties:
                      version:
                        type: string
                      checksums_url:
                        type: string
                        format: uri
                        description: SHA-256 sums of every binary of that version.
        '400':
          $ref: '#/components/responses/InvalidJSON'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/RunNotActive'
        '422':
          $ref: '#/components/responses/InvalidRequest'
        '429':
          description: The run has its limit of connectors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  responses:
    InvalidJSON:
      description: The body is not one strict JSON value of the documented shape (`invalid_json`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: No such object in this organisation (`not_found`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InvalidRequest:
      description: A field is invalid; the message names it (`invalid_request`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The credential lacks the permission or scope, or names another organisation (`forbidden`, `insufficient_scope`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: No credential, an invalid one, or a delegated token where none is accepted (`unauthorized`, `invalid_api_key`, `delegated_not_allowed`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RunNotActive:
      description: The run has already ended (`run_not_active`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    RunId:
      name: runId
      in: path
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
            message:
              type: string
            docs:
              type: string
              format: uri
              description: Where the API and its error codes are documented.
        request_id:
          type: string
          description: The X-Ironfang-Request-ID of the failed request.
    Connector:
      type: object
      description: 'One connector to a run. Its credentials never appear here: the bootstrap token is returned once at creation, the session credential once at the gateway.'
      required:
      - id
      - organisation_id
      - run_id
      - routes
      - status
      - bootstrap_expires_at
      - created_at
      properties:
        id:
          type: string
          format: uuid
        organisation_id:
          type: string
          format: uuid
        run_id:
          type: string
          format: uuid
        name:
          type: string
        routes:
          type: array
          items:
            type: string
          description: The route labels the credential is bound to.
        status:
          type: string
          enum:
          - pending
          - online
          - offline
        client:
          type: object
          additionalProperties: true
          description: What the connector said about itself at hello (version, os, arch).
        bootstrap_expires_at:
          type: string
          format: date-time
        bootstrap_used_at:
          type: string
          format: date-time
        session_expires_at:
          type: string
          format: date-time
          description: Never later than the run's expiry.
        connected_at:
          type: string
          format: date-time
        last_seen_at:
          type: string
          format: date-time
        disconnected_at:
          type: string
          format: date-time
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: if_live_ platform API key
      description: 'A platform API key minted in the portal (Warden). Its scopes are its

        permissions - `rig:read`, `rig:write`, `rig:run`,

        `rig:connector`, or `rig:*` - and it acts only in the organisation

        it was minted for. Keys without Rig scopes are refused with 403.

        '
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Warden JWT
      description: 'A Warden user token. Each route also requires a tenant permission in

        the acting tenant (`X-Ironfang-Tenant`), resolved live from Warden:

        reads need `rig.read`; creating and revising projects and suites

        `rig.write`; starting, finishing and cancelling runs and allocating

        resources `rig.run`. A missing permission is 403; a permission

        lookup failure is 503.

        '
externalDocs:
  description: Ironfang Rig documentation
  url: https://ironfang.com/rig/docs