openapi: 3.0.1
info:
  title: Authenticate
  description: >-
    <h2>An API for retrieving your access token for authentication.</h2>


    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.


    -(Not reccommended in a production integration) Alternatively for trying out
    the API, your Compass Application username + password.
servers:
  - url: https://api.blackbird.ai
security: []
x-hideTryItPanel: false
x-codeSamples: true
paths:
  /auth/oauth2/token:
    post:
      summary: Get token
      description: Exchange client credentials 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. The only valid value right now is
                    `client_credentials`
                  enum:
                    - client_credentials
                client_id:
                  type: string
                  description: Your application's client ID.
                client_secret:
                  type: string
                  description: Your application's client secret.
              example:
                grant_type: client_credentials
                client_id: your_client_id
                client_secret: your_client_secret
      responses:
        '200':
          description: Access token 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.
                example:
                  access_token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
                  token_type: Bearer
                  expires_in: 3600
        '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.
  /compass/token:
    post:
      summary: Get token via password grant
      description: Exchange username password via password OAuth grant for an access token.
      operationId: passwordGrantToken
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  description: The grant type. The only valid value right now is `password`
                  enum:
                    - password
                username:
                  type: string
                  description: Your compass username
                password:
                  type: string
                  description: Your compass password
              example:
                grant_type: password
                username: myEmail@gmail.com
                password: myP@ssword123
      responses:
        '200':
          description: Access token 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.
                example:
                  access_token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
                  token_type: Bearer
                  expires_in: 3600
        '400':
          description: Bad Request - Missing or invalid parameters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error_code:
                    type: string
                    description: Error code.
                  msg:
                    type: string
                    description: Description of the error.
components: {}
