BlueConic OAuth 2.0 API

openapi: 3.2.0
info:
  title: BlueConic REST API v2 OAuth 2.0 API
  description: Welcome to the BlueConic REST API v2.
  termsOfService: https://www.blueconic.com/blueconic-terms-and-conditions
  contact:
    name: Contact us
    url: https://support.blueconic.com/hc/en-us/requests/new
  license:
    name: BlueConic
    url: https://github.com/blueconic/openapi/blob/main/LICENSE.MD
  version: '100.0'
servers:
- url: https://{blueconicHostname}/rest/v2
  description: The BlueConic server
  variables:
    blueconicHostname:
      description: BlueConic server hostname, e.g. 'tenant.blueconic.net'
      default: tenantname
tags:
- name: OAuth 2.0
  description: The OAuth 2.0 API allows external applications to be authenticated and authorized to access the public BlueConic API. The OAuth 2.0 specification is implemented according to RFC 6749.
paths:
  /oauth/authorize:
    get:
      tags:
      - OAuth 2.0
      summary: Start Authorization Code Flow
      description: Starts the Authorization Code Flow. The user will be redirected to the authorization server where the user can grant or deny the external application access. The Proof Key for Code Exchange (PKCE) extension is enforced for the Authorization Code Flow.
      operationId: startAuthorizationCodeFlow
      parameters:
      - name: response_type
        in: query
        description: The response type. Currently only supports the authorization code grant type.
        required: true
        schema:
          type: string
          enum:
          - code
        example: code
      - name: client_id
        in: query
        description: The client ID of the external application. The client ID is assigned during client registration.
        required: true
        schema:
          type: string
        example: Zl3QZFUGOKQrABbX2RoGwmgUDOiFAhLq
      - name: redirect_uri
        in: query
        description: The redirect URI to which the user is redirected to after successful authentication. The redirect URI must exactly match the redirect URI provided at client registration.
        required: true
        schema:
          type: string
        example: https://client.example.com/cb
      - name: code_challenge
        in: query
        description: The code challenge for PKCE.
        required: true
        schema:
          type: string
        example: 4MwafmutlwDy7ly8QOtO-bUvSVzU3I_OQEDgmB3Pn5A
      - name: code_challenge_method
        in: query
        description: The code challenge method for PKCE.
        schema:
          type: string
          default: PLAIN
          enum:
          - PLAIN
          - S256
        example: S256
      - name: state
        in: query
        description: An opaque value provided by the client to maintain state between the request and redirect URI. The state value is added to the redirect URI upon redirection.
        schema:
          type: string
        example: xyz
      responses:
        '302':
          description: Redirects to the redirect URI with the error added to the query component of the redirect URI.
        '303':
          description: Redirects to the authorization server.
        '400':
          description: One or more required parameters are missing or invalid.
        '503':
          description: The server is too busy to handle the request.
  /oauth/revoke:
    post:
      tags:
      - OAuth 2.0
      summary: Revoke token
      description: Revokes access and/or refresh tokens.
      operationId: revokeToken
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                token:
                  type: string
                  description: The access or refresh token to revoke.
                client_id:
                  type: string
                  description: The client id is a unique identifier assigned to a client application.
                client_secret:
                  type: string
                  description: The client secret is a confidential string used for authentication in OAuth 2.0.
                token_type_hint:
                  type: string
                  description: A token type hint to optimize token retrieval during revocation. The token type hint will be ignored if it contains an invalid value.
                  enum:
                  - access_token
                  - refresh_token
              required:
              - client_id
              - client_secret
              - token
      responses:
        '200':
          description: Token has been revoked.
        '400':
          description: One or more required parameters are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenErrorResponse'
              examples:
                Example response:
                  description: Example response
                  value: "{\n  \"error_description\": \"Unsupported grant type\",\n  \"error\": \"unsupported_grant_type\"\n}"
        '401':
          description: Authentication failed (unauthorized).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenErrorResponse'
              examples:
                Example response:
                  description: Example response
                  value: "{\n  \"error_description\": \"Client authentication failed\",\n  \"error\": \"invalid_client\"\n}"
        '503':
          description: The server is too busy to handle the request.
  /oauth/token:
    post:
      tags:
      - OAuth 2.0
      summary: Get token
      description: Obtains an access token and optional refresh token by presenting an authorization grant or refresh token. Refresh Token Rotation is supported by default for the Authorization Code Flow.
      operationId: getToken
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  description: The grant type.
                  enum:
                  - authorization_code
                  - client_credentials
                  - refresh_token
                client_id:
                  type: string
                  description: The client id is a unique identifier assigned to a client application.
                client_secret:
                  type: string
                  description: The client secret is a confidential string used for authentication in OAuth 2.0.
                code:
                  type: string
                  description: The authorization code, which serves as the grant. Only required when `grant_type=authorization_code`.
                redirect_uri:
                  type: string
                  description: The redirect URI passed in the authorization request. Only required when `grant_type=authorization_code`.
                code_verifier:
                  type: string
                  description: The code verifier for PKCE.
                refresh_token:
                  type: string
                  description: The refresh token with which to obtain a new access and refresh token. Only required when `grant_type=refresh_token`.
              required:
              - client_id
              - client_secret
              - grant_type
      responses:
        '200':
          description: Returns an access token and optional refresh token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenSuccessResponse'
              examples:
                Example response:
                  description: Example response
                  value: "{\n  \"access_token\": \"2YotnFZFEjr1zCsicMWpAA\",\n  \"refresh_token\": \"tGzv3JOkF0XG5Qx2TlKWIB\",\n  \"token_type\": \"Bearer\",\n  \"expires_in\": 3600\n}"
        '400':
          description: One or more required parameters are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenErrorResponse'
              examples:
                Example response:
                  description: Example response
                  value: "{\n  \"error_description\": \"Unsupported grant type\",\n  \"error\": \"unsupported_grant_type\"\n}"
        '401':
          description: Authentication failed (unauthorized).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenErrorResponse'
              examples:
                Example response:
                  description: Example response
                  value: "{\n  \"error_description\": \"Client authentication failed\",\n  \"error\": \"invalid_client\"\n}"
        '503':
          description: The server is too busy to handle the request.
components:
  schemas:
    TokenErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: The error code.
        error_description:
          type: string
          description: A human-readable description of the error with additional information.
    TokenSuccessResponse:
      type: object
      properties:
        access_token:
          type: string
          description: The access token that gives access to the public API.
        expires_in:
          type: integer
          format: int32
          description: The time in seconds after which the access token will expire.
        refresh_token:
          type: string
          description: The refresh token with which a new access and refresh token can be obtained.
        token_type:
          type: string
          description: The token type of the access and refresh token.
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'Authenticates a registered OAuth 2.0 client. The Authorization code flow and Client credentials flow are supported. Make sure to select the correct flow based on which flow the registered client supports. The client id and client secret can be found in BlueConic by opening the registered client under *Settings* > *Access management* > *Applications*.<br/>**NOTE:** When using the Authorization code flow, the redirect URL of the registered client in BlueConic must be set to `https://rest.apidoc.blueconic.com/oauth-receiver.html` and ''Send Proof Key for Code Exchange'' must be enabled.<br/><br/>To use a Bearer token for authentication, follow these steps: <br/>1. Acquire the token through authentication.<br/>2. Include the token in the request''s Authorization header as Bearer \<token\>.<br/>3. Send the request to access protected resources.<br/>4. Handle token expiration by refreshing or obtaining a new token.'
      flows:
        clientCredentials:
          tokenUrl: /rest/v2/oauth/token
        authorizationCode:
          authorizationUrl: /rest/v2/oauth/authorize
          tokenUrl: /rest/v2/oauth/token
          refreshUrl: /rest/v2/oauth/token