openapi: 3.0.1
info:
  description: |-
    API for issuing Billetautomat (BAT) JWT tokens to authenticate the caller, for use 
    with services published by CESOP-DK.

    This API specification supplements the CESOP instructions found at [www.skat.dk/CESOP](https://www.skat.dk/CESOP)
  title: BAT Token Issuer
  version: 1.0.0
servers:
  - description: PROD
    url: https://oces.billetautomat.skat.dk
  - description: TFE
    url: https://oces.billetautomat.tfe.skat.dk
tags:
  - name: token
    description: Issued by BAT
paths:
  /auth/realms/oces/certificates/cert:
    post:
      tags:
        - token
      description: |-
        Request a BAT token authenticating a valid OCES certificate identifying the caller, used when establishing the mTLS connection.

        **NOTE:** It is a prerequisite that a valid OCES certificate identifying the caller
        is being used for establishing the mTLS connection with the BAT endpoint.
      operationId: RequestToken
      requestBody:
        description: Request a BAT token
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
            examples:
              "self":
                description: The caller is identified af 'self'
                value:
                  client_id: cesop-api
                  nonce:   cdf29e73-0b06-4ee8-8ee4-09a383c8361a
              "on behalf of company":
                description: The caller is identified as calling on behalf of another party
                value:
                  client_id: cesop-api
                  paa_vegne_af_se: 88664422
                  nonce:   cdf29e73-0b06-4ee8-8ee4-09a383c8361a
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
          description: A BAT token for the authenticated caller
        "400":
          content:
            text/html:
              example: A description of error
          description: Invalid values was provided as parameters for the request
      summary: Request BAT token
components:
  schemas:
    TokenRequest:
      required:
        - client_id
        - nonce
      type: object
      description: BAT token request parameters
      properties:
        client_id:
          type: string
          description: ID used to identify the context for the issued token. Always `cesop-api`
          example: cesop-api
        paa_vegne_af_se:
          type: string
          description: |-
            The company identification number (SE) when the certificate holder is calling the CESOP services on behalf of said company
          example: 88664422
        nonce:
          type: string
          format: uuid
          description: Unique request identifier provided by the caller
          example: cdf29e73-0b06-4ee8-8ee4-09a383c8361a
      title: Token Request
    TokenResponse:
      required:
        - access_token
        - token_type
        - expires_in
        - scope
      type: object
      description: BAT token response
      properties:
        access_token:
          type: string
          description: Bearer token, issued by BAT, authenticating the caller
          example: |-
            eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJZbkxaeURUMXktV0ZqVWhYVWl2U2NIMWgyQ3p4WlFiS01jek5KT080WkxnIn0...
        token_type:
          type: string
          description: The type of the issued token. Always `Bearer`
          example: Bearer
        expires_in:
          type: integer
          format: uuid
          description: The duration of validity for the issued token, specified in seconds
          example: 180
        scope:
          type: string
          description: The scope forthe issued token. Always `openid certToJWT cesop-api`
          example: openid certToJWT cesop-api
      title: Token Response