openapi: 3.1.0
info:
  title: API Authentication
  description: >
    ## Summary

    Bandwidth uses an authorization server for our products that works within
    the OpenID Connect (OIDC) and OAuth 2.0 protocols for delegated
    authentication. Primarily, it generates access tokens in the form of JSON
    Web Tokens (JWTs) and exposes issuers that can be used to validate the
    tokens minted.

    This API is specific to the OAuth 2.0 functionality, which includes minting
    tokens and retrieving signing keys.


    ## Base URL


    `https://api.bandwidth.com/`
  version: 1.0.0
  contact:
    name: Bandwidth
  termsOfService: https://www.bandwidth.com/legal/terms-of-use-bandwidthcom-web-sites/
servers:
  - url: https://api.bandwidth.com
paths:
  /.well-known/openid-configuration:
    get:
      summary: Metadata
      description: >-
        Retrieves metadata about the Bandwidth Authorization Server. This
        includes the issuer URL, token endpoint, and JWKs endpoint.
      operationId: retrieveWellKnown
      tags:
        - .well-known
      responses:
        '200':
          $ref: '#/components/responses/wellKnownResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '403':
          $ref: '#/components/responses/forbiddenResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '405':
          $ref: '#/components/responses/methodNotAllowedResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/runtimeExceptionResponse'
  /api/v1/oauth2/token:
    post:
      summary: Mint Token
      description: >-
        Mints a new access token in the form of a JSON Web Token (JWT) for a
        client.
      security:
        - Basic: []
      operationId: generateToken
      tags:
        - Token
      requestBody:
        $ref: '#/components/requestBodies/tokenRequest'
      responses:
        '200':
          $ref: '#/components/responses/tokenResponse'
        '400':
          $ref: '#/components/responses/tokenBadRequestResponse'
        '401':
          $ref: '#/components/responses/unauthorizedResponse'
        '403':
          $ref: '#/components/responses/forbiddenResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '405':
          $ref: '#/components/responses/methodNotAllowedResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/runtimeExceptionResponse'
  /api/v1/oauth2/keys:
    get:
      summary: Signing Keys
      description: >-
        Retrieves the set of JSON Web Keys (JWKs) used to sign the access tokens
        that are minted for the client.
      operationId: retrieveKeys
      tags:
        - JWKs
      responses:
        '200':
          $ref: '#/components/responses/keysResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '403':
          $ref: '#/components/responses/forbiddenResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '405':
          $ref: '#/components/responses/methodNotAllowedResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/runtimeExceptionResponse'
components:
  securitySchemes:
    Basic:
      type: http
      scheme: basic
  requestBodies:
    tokenRequest:
      description: The request body for generating a token.
      content:
        application/x-www-form-urlencoded:
          schema:
            $ref: '#/components/schemas/tokenRequest'
  responses:
    wellKnownResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/metaData'
    badRequestResponse:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            badRequestResponseExample:
              $ref: '#/components/examples/badRequestResponseExample'
    tokenBadRequestResponse:
      description: Bad Token Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/tokenErrorResponse'
          examples:
            badRequestResponseExample:
              $ref: '#/components/examples/tokenBadRequestResponseExample'
    forbiddenResponse:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            forbiddenResponseExample:
              $ref: '#/components/examples/forbiddenResponseExample'
    notFoundResponse:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            notFoundResponseExample:
              $ref: '#/components/examples/notFoundResponseExample'
    methodNotAllowedResponse:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            methodNotAllowedResponseExample:
              $ref: '#/components/examples/methodNotAllowedResponseExample'
    tooManyRequestsResponse:
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            tooManyRequestsResponseExample:
              $ref: '#/components/examples/tooManyRequestsResponseExample'
    runtimeExceptionResponse:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            runtimeExceptionResponseExample:
              $ref: '#/components/examples/runtimeExceptionResponseExample'
    tokenResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/token'
    unauthorizedResponse:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/tokenErrorResponse'
          examples:
            unauthorizedResponseExample:
              $ref: '#/components/examples/unauthorizedResponseExample'
    keysResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/keys'
  schemas:
    tokenRequest:
      title: tokenForm
      type: object
      required:
        - grant_type
      properties:
        grant_type:
          $ref: '#/components/schemas/grantTypeEnum'
        scope:
          type: string
    metaData:
      title: authServiceMetaData
      type: object
      properties:
        issuerUrl:
          type: string
          readOnly: true
          description: >-
            The URL of the issuer of a token. Should be the base API URL of the
            resource server
          example: https://api.bandwidth.com/api/v1
        issuer:
          type: string
          readOnly: true
          description: >-
            The URL of the issuer of a token. Should be the base API URL of the
            resource server
          example: https://api.bandwidth.com/api/v1
        jwks_endpoint:
          type: string
          readOnly: true
          description: >-
            The URL used to retrieve the JSON Web Keys (JWKs) that are used to
            sign access tokens.
          example: https://api.bandwidth.com/api/v1/oauth2/keys
        token_endpoint:
          type: string
          readOnly: true
          description: >-
            The URL used to generate access tokens in the form of JSON Web
            Tokens (JWTs).
          example: https://api.bandwidth.com/api/v1/oauth2/token
        alt_issuers:
          type: array
          description: A list of alternate issuer URLs that can also verify minted tokens
          items:
            type: string
            description: A URL to an alternate issuer that can also verify minted tokens
            example: https://api.bandwidth.com/api/v1
        token_endpoint_auth_methods_supported:
          type: array
          description: A list of authentication methods supported by the token endpoint
          items:
            type: string
          example:
            - client_secret_basic
    tokenErrorResponse:
      required:
        - error
        - error_description
        - error_uri
      type: object
      properties:
        error:
          type: string
          readOnly: true
          description: The type of token error
          example: invalid_client
        error_description:
          type: string
          readOnly: true
          description: The error description
          example: Provided client credentials are invalid
        error_uri:
          type: string
          readOnly: true
          description: The OAuth2 error URI
          example: https://tools.ietf.org/html/rfc6749#section-5.2
        err:
          $ref: '#/components/schemas/error'
    errorResponse:
      required:
        - links
        - data
        - errors
      type: object
      additionalProperties: false
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/link'
          example: []
        data:
          type: object
          nullable: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
          example: []
    token:
      title: tokenResponse
      type: object
      required:
        - access_token
        - access_token_id
        - token_type
        - expires_in
      properties:
        access_token:
          description: The JSON Web Token (JWT) with various properties encoded.
          type: string
          readOnly: true
          example: >-
            eyJraWQiOiJrZXktMTIzIiwia2lkIjoiY2xpZW50LTEyMyIsInN1YiI6ImFjY291bnQtMTIzIiwidHlwZSI6IkpXVCIsImF1ZCI6ImFjY291bnQtMTIzIn0.eyJleHBpcmVkX3Njb3BlcyI6WyJhcGkiLCJwcm9maWxlIl0sImV4cCI6MTYzMjQwMDAwMCwiaWF0IjoxNjMyMzkwMDAwLCJqdGkiOiIxMjM0NTY3ODkwIn0
        access_token_id:
          description: >-
            The ID of the access token to prevent tokens from being re-used.
            Same as the `jti` claim within the access token.
          type: string
          readOnly: true
          example: 1234567890abcdef
        token_type:
          $ref: '#/components/schemas/tokenTypeEnum'
        expires_in:
          description: The amount of time until this token expires in seconds.
          type: number
          readOnly: true
          example: 3600
    keys:
      title: keysResponse
      type: object
      required:
        - keys
      properties:
        keys:
          description: >-
            A collection of available keys that are used to sign and verify
            tokens
          type: array
          items:
            $ref: '#/components/schemas/key'
    grantTypeEnum:
      type: string
      enum:
        - client_credentials
      description: The OAuth 2.0 grant type.
    link:
      title: link
      type: object
      additionalProperties: false
      properties:
        href:
          type: string
          description: The URI of the link
          example: https://api.bandwidth.com/api/v1/credentials
        rel:
          type: string
          description: The relationship of the link to the resource
          example: self
        method:
          type: string
          description: The HTTP method to use when following the link
          example: GET
    error:
      title: error
      type: object
      additionalProperties: false
      properties:
        type:
          type: string
          description: A short human-readable summary of the problem encountered
          example: Error
        description:
          type: string
          description: >-
            A human-readable detailed description that SHOULD be specific to the
            problem encountered
          example: There was a problem with your request. Please try again
        code:
          type: string
          description: An Auth Service API specific error code
          example: E0001
        source:
          type: object
          description: Information about the source of the error
          additionalProperties: false
          properties:
            field:
              type: string
              description: The field in the request that caused the error
              example: lastName
        meta:
          type: object
          description: Additional metadata about the error
          additionalProperties: false
          properties:
            traceId:
              type: string
              description: A unique identifier for the error
              example: '123456789'
    tokenTypeEnum:
      type: string
      enum:
        - Bearer
      description: The type of token being created. Currently only supports Bearer.
    key:
      title: key
      type: object
      required:
        - kty
        - use
        - alg
        - kid
        - 'n'
        - e
      properties:
        alg:
          $ref: '#/components/schemas/keyAlgorithmEnum'
        kty:
          $ref: '#/components/schemas/keyTypeEnum'
        use:
          $ref: '#/components/schemas/keyUseEnum'
        x5c:
          description: >-
            The x.509 certificate chain. The first entry in the array is the
            certificate to use for token verification; the other certificates
            can be used to verify this first certificate.
          type: array
          items:
            type: string
        'n':
          description: The modulus for the RSA public key.
          type: string
        e:
          description: The exponent for the RSA public key.
          type: string
        kid:
          description: The unique identifier for the key.
          type: string
        x5t:
          description: The thumbprint of the x.509 cert (SHA-1 thumbprint).
          type: string
    keyAlgorithmEnum:
      type: string
      enum:
        - RS256
      description: The specific cryptographic algorithm used with the key.
      readOnly: true
    keyTypeEnum:
      type: string
      enum:
        - RSA
      description: The family of cryptographic algorithms used with the key.
      readOnly: true
    keyUseEnum:
      type: string
      enum:
        - sig
      description: How the key was meant to be used; sig represents the signature.
  examples:
    badRequestResponseExample:
      value:
        links: []
        data: null
        errors:
          - type: validation
            description: accountScope is a required field
            code: '1003'
            source:
              field: accountScope
            meta:
              traceId: '123456789'
    tokenBadRequestResponseExample:
      value:
        error: invalid_client
        error_description: Missing or malformed basic auth credentials
        error_uri: https://tools.ietf.org/html/rfc6749#section-5.2
        err:
          type: authentication-credentials
          description: Missing or malformed basic auth credentials.
          code: '1003'
    forbiddenResponseExample:
      value:
        links: []
        data: null
        errors:
          - type: resource-permissions
            description: You do not have permission to access this resource.
            code: '1002'
            meta:
              traceId: '123456789'
    notFoundResponseExample:
      value:
        links: []
        data: null
        errors:
          - type: not-found
            description: the specified resource could not be found.
            code: '1024'
            meta:
              traceId: '123456789'
    methodNotAllowedResponseExample:
      value:
        links: []
        data: null
        errors:
          - type: http-method-not-supported
            description: The HTTP method used is not allowed for this resource.
            code: '1004'
            source:
              field: method
            meta:
              traceId: '123456789'
    tooManyRequestsResponseExample:
      value:
        links: []
        data: null
        errors:
          - type: rate-limiting
            description: You have exceeded the rate limit for this resource.
            code: '1005'
            meta:
              traceId: '123456789'
    runtimeExceptionResponseExample:
      value:
        links: []
        data: null
        errors:
          - type: internal-error
            description: An unexpected error occurred. Please try again later.
            code: '1010'
            meta:
              traceId: '123456789'
    unauthorizedResponseExample:
      value:
        error: invalid_client
        error_description: Provided client credentials are invalid
        error_uri: https://tools.ietf.org/html/rfc6749#section-5.2
        err:
          type: authentication-credentials
          description: provided client credentials are invalid.
          code: '1001'
security: []
tags:
  - name: .well-known
  - name: Token
  - name: JWKs
