openapi: 3.2.0
info:
  description: Fusebit HTTP API for the management and execution of Fusebit accounts, users, functions and more
  version: 1.0.0
  title: Fusebit HTTP API - Core Clients API
  contact:
    email: contact@fusebit.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.{region}.on.fusebit.io
  description: Production
  variables:
    region:
      description: The region where the API is deployed, for example `'us-west-1'`
      default: us-west-1
security:
- AccessToken: []
tags:
- name: Clients
  description: Client management operations
paths:
  /v1/account/{accountId}/client:
    parameters:
    - in: path
      name: accountId
      required: true
      description: Account id
      schema:
        $ref: '#/components/schemas/AccountId'
    get:
      tags:
      - Clients
      summary: Get clients of an account
      operationId: getAccountClientList
      description: 'Returns a list of clients associated with the given account.


        Use query string parameters to filter the list of clients.

        All query filters are combined with a logical AND operator.'
      parameters:
      - in: query
        name: include
        required: false
        description: 'Optional switch to include all properties of the clients in the response.

          If this switch is not provided only the `id` and `displayName` fields of each client are returned in the response.

          '
        schema:
          type: string
          enum:
          - all
      - in: query
        name: name
        required: false
        description: 'Optional identifier to match against the `displayName` field of the clients. Matching is case-sensitive. Partial

          matches are supported.

          '
        schema:
          type: string
      - in: query
        name: issuerId
        required: false
        description: 'Optional identifier to match against the `issuerId` field of the identities of the clients.

          Matching is case-sensitive. The full issuer id must be provided as partial matches are not supported.

          '
        schema:
          $ref: '#/components/schemas/IssuerId'
      - in: query
        name: subject
        required: false
        description: 'Optional identifier to match against the `subject` field of the identities of the clients.

          Only valid if the `issuerId` query filter is also provided. Matching is case-sensitive.

          The full subject must be provided as partial matches are not supported.

          '
        schema:
          type: string
      - in: query
        name: next
        required: false
        description: Opaque token to start returning results from
        schema:
          type: string
      - in: query
        name: count
        required: false
        description: Optional number of results to return
        schema:
          type: number
          minimum: 1
          maximum: 100
      responses:
        200:
          description: A list of clients
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientList'
        400:
          description: Malformed account id or invalid query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: Not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - AccessToken:
        - client:get
    post:
      tags:
      - Clients
      summary: Add a client
      operationId: postClient
      description: Adds a client to given account.
      requestBody:
        description: The new client to add
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewClient'
      responses:
        200:
          description: The client that was added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Client'
        400:
          description: Malformed account id or invalid client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: Not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - AccessToken:
        - client:add
  /v1/account/{accountId}/client/{clientId}:
    parameters:
    - in: path
      name: accountId
      required: true
      description: Account id
      schema:
        $ref: '#/components/schemas/AccountId'
    - in: path
      name: clientId
      required: true
      description: Client id
      schema:
        $ref: '#/components/schemas/ClientId'
    get:
      tags:
      - Clients
      summary: Get a client of an account
      operationId: getAccountClient
      description: Returns a client associated with the given account.
      responses:
        200:
          description: The client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Client'
        400:
          description: Malformed account or client id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: Not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: Client not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - AccessToken:
        - client:get
    patch:
      tags:
      - Clients
      summary: Update a client of an account
      operationId: putAccountClient
      description: Updates a client associated with the given account.
      requestBody:
        description: The client to update
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewClient'
      responses:
        200:
          description: The client that was updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Client'
        400:
          description: Malformed account or client id, or invalid client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: Not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: Client not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - AccessToken:
        - client:update
    delete:
      tags:
      - Clients
      summary: Delete a client of an account
      description: Deletes a client that was previously associated with the given account.
      operationId: deleteClient
      responses:
        204:
          description: Client was deleted
        400:
          description: Malformed account or client id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: Not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: Client not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - AccessToken:
        - client:delete
  /v1/account/{accountId}/client/{clientId}/init:
    parameters:
    - in: path
      name: accountId
      required: true
      description: Account id
      schema:
        $ref: '#/components/schemas/AccountId'
    - in: path
      name: clientId
      required: true
      description: Client id
      schema:
        $ref: '#/components/schemas/ClientId'
    post:
      tags:
      - Clients
      summary: Create an initialization token for an existing client
      operationId: initClient
      description: 'Create an initialization token for an existing client.

        The initialization token is a single-use bearer credential that allows the caller to add a new identity for the client.

        If unused, the initialization token expires after eight hours.'
      requestBody:
        description: The parameters for the initialization token
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitRequest'
      responses:
        200:
          description: The initialization token was generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitResponse'
        400:
          description: Malformed initialization token parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: Not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - AccessToken:
        - client:init
components:
  schemas:
    BoundaryId:
      type: string
      description: Boundary id
      example: my-boundary-xyz
    NewClient:
      type: object
      properties:
        displayName:
          type: string
          description: The client's display name
          example: production-service
        identities:
          type: array
          items:
            $ref: '#/components/schemas/Identity'
        access:
          type: object
          properties:
            allow:
              type: array
              items:
                $ref: '#/components/schemas/AccessStatement'
    Error:
      type: object
      required:
      - status
      - statusCode
      - message
      properties:
        status:
          type: number
          description: The HTTP status code
          example: 404
        statusCode:
          type: number
          description: The HTTP status code
          example: 404
        message:
          type: string
          description: A message with details regarding the error
          example: The user 'usr-5555555555555555' does not exist
    FunctionId:
      type: string
      description: Function id
      example: my-function-abc
    Client:
      allOf:
      - type: object
        required:
        - id
        properties:
          id:
            $ref: '#/components/schemas/ClientId'
      - $ref: '#/components/schemas/NewClient'
    InitProtocol:
      type: string
      enum:
      - pki
      - oauth
      description: "The initialization token protocol that determines the type of the source of trust for validating access tokens the user or client will present when making HTTP API calls:\n  * `pki` - when adding an indentity to the user or client, the caller must present a public key that can be used to validate signatures of access tokens\n  * `oauth` - when adding an indentity to the user or client, the caller must indicate a trusted issuer of access tokens that is already pre-configured in the system\n"
    IssuerId:
      type: string
      description: Issuer id
      example: https://auth-server.company-abc.com
    AccountId:
      type: string
      description: Account id
      example: acc-5555555555555555
    ClientList:
      type: object
      required:
      - items
      properties:
        next:
          type: string
          description: Opaque token to continue getting results from
        items:
          type: array
          description: A list of clients
          items:
            $ref: '#/components/schemas/Client'
    ClientId:
      type: string
      description: Client id
      example: clt-5555555555555555
    SubscriptionId:
      type: string
      description: Subscription id
      example: sub-5555555555555555
    Identity:
      type: object
      required:
      - issuerId
      - subject
      properties:
        issuerId:
          $ref: '#/components/schemas/IssuerId'
        subject:
          type: string
          description: The `sub` claim value in access tokens
    InitRequest:
      type: object
      required:
      - protocol
      - profile
      properties:
        protocol:
          $ref: '#/components/schemas/InitProtocol'
        profile:
          type: object
          description: 'Additional information to be included in the initialization token for consumption by the intended recipient of the token.

            For example, this information can be used to include default parameters of the CLI profile or OAuth parameters that indicate the identity provider to use.

            '
          properties:
            subscription:
              description: The default subscription id the caller should use
              $ref: '#/components/schemas/SubscriptionId'
            boundary:
              description: The default boundary id the caller should use
              $ref: '#/components/schemas/BoundaryId'
            function:
              description: The default function id the caller should use
              $ref: '#/components/schemas/FunctionId'
            oauth:
              type: object
              description: Parameters the caller should use when obtaining an access token from an OAuth identity provider
              properties:
                webAuthorizationUrl:
                  type: string
                  description: The authorization URL to initiate OAuth implicit flow
                webClientId:
                  type: string
                  description: The OAuth client id to use when initializing OAuth implicit flow
                webLogoutUrl:
                  type: string
                  description: The URL to navigate to to log a browser client out from the OAuth identity provider
                deviceAuthorizationUrl:
                  type: string
                  description: The authorization URL to initiate OAuth device flow
                deviceClientId:
                  type: string
                  description: The OAuth client id to use when initializing OAuth device flow
                tokenUrl:
                  type: string
                  description: The OAuth URL to use to exchange refresh tokens for access tokens
    InitResponse:
      type: string
      description: 'A single-use initialization token in JWT format. If unused, the token expires in eight hours. The `profile`

        parameter of the JWT payload contains the information specified in the `profile` parameter of the request

        as well as additional information for consumption by the intended recipient of the token.

        '
    AccessStatement:
      type: object
      required:
      - action
      - resource
      properties:
        action:
          type: string
          description: The action to perform
          example: function:*
        resource:
          type: string
          description: The resource to perform the action on
          example: /account/acc-5555555555555555/subscription/sub-5555555555555555/boundary/my-boundary-1/function/my-function-17
  securitySchemes:
    AccessToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: For a description of the access token format, see [this doc](../../integrator-guide/authz-model).