openapi: 3.0.1
info:
  title: Authenticate
  summary: <b>An API for retrieving your access token for authentication.</b>
  description: >-
    This guide will help you connect to our API using OAuth authentication. This
    document will guide you through setting up and using these authentication
    methods in your preferred programming language. For reference, you can also
    try out your authentication and the entire API in the [OpenAPI
    Spec](https://api.blackbird.ai/compass/openapi/#/ContextChecks).



    <b>Prerequisites</b>


    Before you begin, ensure you have the following:



    -A Blackbird AI account.


    -Your client credentials (Client ID and Client Secret) for the Client
    Credentials flow.
servers:
  - url: https://blackbird-ai.auth.us-west-2.amazoncognito.com
x-hideTryItPanel: false
x-codeSamples: true
paths:
  /oauth2/token:
    post:
      summary: Get token
      description: Exchange authorization code or refresh token for an access token.
      operationId: token
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  description: >-
                    The grant type. Either `authorization_code` or
                    `refresh_token`.
                  enum:
                    - authorization_code
                    - refresh_token
                code:
                  type: string
                  description: >-
                    The authorization code received from the authorization
                    server (required if `grant_type` is `authorization_code`).
                refresh_token:
                  type: string
                  description: >-
                    The refresh token (required if `grant_type` is
                    `refresh_token`).
                client_id:
                  type: string
                  description: Your application's client ID.
                client_secret:
                  type: string
                  description: Your application's client secret.
                redirect_uri:
                  type: string
                  description: >-
                    The redirect URI, which should match the one used in the
                    authorization request (only required for
                    `authorization_code` grant type).
              example:
                grant_type: client_credentials
                client_id: your_client_id
                client_secret: your_client_secret
      responses:
        '200':
          description: Access token and refresh token are returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    description: The access token to use for API requests.
                  token_type:
                    type: string
                    description: Token type, typically "Bearer".
                  expires_in:
                    type: integer
                    description: Time in seconds until the access token expires.
                  refresh_token:
                    type: string
                    description: >-
                      The refresh token for obtaining a new access token when
                      the current one expires.
                example:
                  access_token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
                  token_type: bearer
                  expires_in: 3600
                  expires_at: 1728577218
                  refresh_token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        '400':
          description: Bad Request - Missing or invalid parameters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error code.
                  error_description:
                    type: string
                    description: Description of the error.
        '401':
          description: Unauthorized - Invalid client credentials.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error code.
                  error_description:
                    type: string
                    description: Description of the error.
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://api.blackbird.ai/compass/authorize
          tokenUrl: https://api.blackbird.ai/compass/token
          scopes:
            read: Read access to the API
            write: Write access to the API
