openapi: 3.0.1
info:
  title: Stratech Identity
  description: ''
  version: 1.0.0
servers:
  - url: https://identity.stratechbooking.nl
paths:
  /connect/token:
    post:
      summary: Endpoint for getting tokens.
      description: |-
        There are 4 different flows that can be used on this endpoint.
        - The client_credential flow
        - The authorization_code flow.
        - The refresh_token flow.
        - The token_exchange flow.

        See `Examples` for more information about the different flows.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - $ref: '#/components/schemas/ClientCredentialsRequest'
                - $ref: '#/components/schemas/AuthorizationCodeRequest'
                - $ref: '#/components/schemas/RefreshTokenRequest'
            examples:
              ClientCredentials:
                summary: client_credentials flow
                description: >2-
                   This flow is used for getting a token that can receive `partner` data.

                  You will have received the `client_id` and `client_secret`
                  from your Stratech contact. 
                value:
                  client_id: example_client
                  client_secret: secret
                  grant_type: client_credentials
              AuthorizationCode:
                summary: authorization_code flow
                description: >-

                  This flow is used for getting a `refresh_token` which is used
                  in the `refresh_token` flow


                  You will have received the `client_id` from your Stratech
                  contact. The `code` and `redirect_uri` are delivered to you
                  through the webhook. 
                value:
                  client_id: example_client
                  client_secret: secret
                  code: example_code
                  grant_type: authorization_code
                  redirect_uri: example_redirect_uri
              RefreshToken:
                summary: refresh_token flow
                description: >2
                   This flow is used for getting a token that can receive `organization` data

                  The `refresh_token` can be requested with the
                  `authorization_code` flow.
                value:
                  client_id: example_client
                  client_secret: secret
                  refresh_token: example_refresh_token
                  grant_type: refresh_token
              TokenExchange:
                summary: token_exchange flow
                description: >-

                  This flow is used for getting a `delegation_token` which is
                  used for the self service endpoints

                  You will have received the `client_id` from your Stratech
                  contact. The value for the `subject_token` is the
                  `access_token` from the self service website. 
                value:
                  client_id: example_client
                  client_secret: secret
                  subject_token: the `access_token` to be delegated
                  subject_token_type: urn:ietf:params:oauth:token-type:access_token
                  grant_type: urn:ietf:params:oauth:grant-type:token-exchange
                  exchange_style: delegation
      responses:
        '200':
          description: >-
            token response, see the examples for more information about the
            different flows.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ClientCredentialsResponse'
                  - $ref: '#/components/schemas/AuthorizationCodeResponse'
                  - $ref: '#/components/schemas/RefreshTokenResponse'
              examples:
                ClientCredentials:
                  summary: client_credentials flow
                  description: use the `access_token` for retrieving `partner` data.
                  value:
                    access_token: example_access_token
                    expires_in: 3600
                    token_type: bearer
                    scope: booking.partner
                AuthorizationCode:
                  summary: authorization_code flow
                  description: use the `refresh_token` in the `refresh_token` flow.
                  value:
                    id_token: example_id_token
                    access_token: example_access_token
                    expires_in: 3600
                    token_type: bearer
                    refresh_token: example_refresh_token
                    scope: booking.partner
                RefreshToken:
                  summary: refresh_token flow
                  description: use the `access_token` for retrieving `organization` data.
                  value:
                    id_token: example_id_token
                    access_token: example_access_token
                    expires_in: 3600
                    token_type: bearer
                    refresh_token: example_refresh_token
                    scope: booking.partner
                TokenExchange:
                  summary: token_exchange flow
                  description: use the `access_token` for the `self service` endpoints.
                  value:
                    access_token: example_access_token
                    expires_in: 3600
                    token_type: bearer
                    refresh_token: example_refresh_token
                    scope: booking.partner
                    issued_token_type: urn:ietf:params:oauth:token-type:access_token
        '400':
          description: >-
            Bad request, see the different examples for more information about
            possible errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InvalidGrant:
                  summary: Invalid grant
                  description: >2-
                     #### authorization_code flow: 
                    - The code has already been used for requesting a refresh
                    token.

                    - The code is expired.

                    - The code is invalid.

                    #### refresh_token flow:

                    - Refresh token is invalid. 
                  value:
                    error: invalid_grant
                UnsupportedGrantType:
                  summary: Invalid client
                  description: Entered wrong client id.
                  value:
                    error: invalid_client
                UnauthorizedClient:
                  summary: Unauthorized client
                  description: |2-
                     - Entered a grant_type that is not allowed for the client.
                    #### authorization_code flow: 
                    - No redirect uri entered. 
                  value:
                    error: unauthorized_client
                InvalidGrantType:
                  summary: Invalid grant type
                  description: Entered a wrong grant_type.
                  value:
                    error: unsupported_grant_type
                InvalidRequest:
                  summary: Invalid request
                  description: Request doesn't contain all required properties.
components:
  schemas:
    ClientCredentialsRequest:
      type: object
      properties:
        client_id:
          type: string
          description: >-
            The client id, you will have received this from your contact at
            Stratech.
        client_secret:
          type: string
          description: >-
            The client secret, you will have received this from your contact at
            Stratech.
        grant_type:
          type: string
          enum:
            - client_credentials
    ClientCredentialsResponse:
      allOf:
        - $ref: '#/components/schemas/TokenResponseBase'
      type: object
      properties:
        access_token:
          type: string
          description: The access token that can be used to receive `partner` data.
    AuthorizationCodeRequest:
      type: object
      properties:
        client_id:
          type: string
          description: >-
            The client id, you will have received this from your contact at
            Stratech.
        client_secret:
          type: string
          description: >-
            The client secret, you will have received this from your contact at
            Stratech.
        code:
          type: string
          description: The code you have received through the configured webhook.
        grant_type:
          type: string
          enum:
            - authorization_code
        redirect_uri:
          type: string
          description: The redirect_uri you have received through the configured webhook.
    AuthorizationCodeResponse:
      allOf:
        - $ref: '#/components/schemas/AccessTokenResponseBase'
    RefreshTokenRequest:
      type: object
      properties:
        client_id:
          type: string
          description: >-
            The client id, you will have received this from your contact at
            Stratech.
        client_secret:
          type: string
          description: >-
            The client secret, you will have received this from your contact at
            Stratech.
        refresh_token:
          type: string
          description: >-
            The refresh token you have received from the authorization_code
            grant.
        grant_type:
          type: string
          enum:
            - refresh_token
    RefreshTokenResponse:
      allOf:
        - $ref: '#/components/schemas/AccessTokenResponseBase'
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: The error message
    AccessTokenResponseBase:
      type: object
      properties:
        id_token:
          type: string
          description: An id_token, this property can be ignored.
        access_token:
          type: string
          description: The access token can be used to receive `organization` data.
        refresh_token:
          type: string
          description: >-
            The refresh token for requesting an access token through the
            authorization_token flow.
      allOf:
        - $ref: '#/components/schemas/TokenResponseBase'
    TokenResponseBase:
      type: object
      properties:
        expires_in:
          type: number
          description: The expiration time in seconds
        token_type:
          type: string
          enum:
            - Bearer
        scope:
          type: string
          enum:
            - booking.partner
