openapi: 3.0.1
info:
  title: IAM OAuth2 API Specification
  description: This specification describes the endpoints of the IAM OAuth2 Service.
  version: 0-SNAPSHOT
servers:
- url: http://localhost
  description: local development host
tags:
- name: IAM OAuth2
  description: OAuth 2 authentication endpoints
paths:
  /oauth2/v1/applications/{application-expression}/tokens/~by-authorization-code:
    post:
      tags:
      - IAM OAuth2
      summary: Create Application OAuth 2 Token using Authorization Code
      description: Complete an OAuth 2 login using the provided authorization code
        and needed details
      operationId: createApplicationOauth2TokenByAuthorizationCode
      parameters:
      - $ref: "#/components/parameters/application-expression"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApplicationOauth2TokenInByAuthorizationCodeV1"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationOauth2TokenV1"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /oauth2/v1/applications/{application-expression}/tokens/~by-refresh-token:
    post:
      tags:
      - IAM OAuth2
      summary: Create Application OAuth 2 Token using Refresh token
      description: Create another OAuth 2 token a previously issued refresh token
      operationId: createApplicationOauth2TokenByRefreshToken
      parameters:
      - $ref: "#/components/parameters/application-expression"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApplicationOauth2TokenInByRefreshTokenV1"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationOauth2TokenV1"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /oauth2/v1/applications/{application-expression}/user-info:
    get:
      tags:
      - IAM OAuth2
      summary: Get Application OAuth 2 UserInfo
      description: Read your user information from the OAuth 2 provider. Relies on
        a previous successful token exchange.
      operationId: getApplicationOauth2UserInfo
      parameters:
      - $ref: "#/components/parameters/Idp-Key"
      - $ref: "#/components/parameters/application-expression"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationOauth2UserInfoV1"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
      - external-token: []
components:
  schemas:
    ApplicationOauth2TokenInByAuthorizationCodeV1:
      required:
      - authorizationCode
      - idpKey
      - redirectUri
      type: object
      properties:
        idpKey:
          maxLength: 64
          minLength: 1
          pattern: "^[a-zA-Z0-9-_.]{1,64}$"
          type: string
          description: An identity provider key which is used to identity a specific
            identity provider configuration.
          example: idp-1
        authorizationCode:
          maxLength: 4096
          minLength: 0
          type: string
          description: The returned authorization code from the OAuth Authorization
            server.
        redirectUri:
          maxLength: 4096
          minLength: 0
          type: string
          description: The used 'redirect_uri' parameter that was used then initiating
            the authentication flow with the OAuth Authorization server.
        codeVerifier:
          maxLength: 4096
          minLength: 0
          type: string
          description: The code verifier used to obtain the authorization code.
      description: Contains required attributes to exchange an authorization code
        for an oauth access token and to create an oauth2 session
    ApplicationOauth2TokenInByRefreshTokenV1:
      required:
      - idpKey
      - refreshToken
      type: object
      properties:
        idpKey:
          maxLength: 64
          minLength: 1
          pattern: "^[a-zA-Z0-9-_.]{1,64}$"
          type: string
          description: An identity provider key which is used to identity a specific
            identity provider configuration.
          example: idp-1
        refreshToken:
          maxLength: 4096
          minLength: 1
          type: string
          description: OAuth2 refresh token to be used to get a new access token
      description: Contains required attributes to exchange a new token via the refresh
        token flow
    ApplicationOauth2TokenV1:
      required:
      - accessToken
      - applicationId
      - idpKey
      type: object
      properties:
        applicationId:
          type: string
          description: The globally unique identifier for an application
        idpKey:
          type: string
          description: An identity provider key which is used to identity a specific
            identity provider configuration.
        accessToken:
          type: string
          description: OAuth2 access token
        accessTokenExpireAt:
          type: string
          description: Expiration time of the access token. This string is formatted
            according to RFC3339.
          format: date-time
        refreshToken:
          type: string
          description: OAuth2 refresh token to be used to get a new access token
        idToken:
          type: string
          description: OIDC ID token
      description: Contains oauth2 token information.
    ApplicationOauth2UserInfoV1:
      required:
      - idpKey
      - subject
      type: object
      properties:
        idpKey:
          type: string
          description: An identity provider key which is used to identity a specific
            identity provider configuration.
        subject:
          type: string
          description: The subject id of the end user
        username:
          type: string
          description: "The username of the end user, usually the email address."
        name:
          type: string
          description: The name of the end user.
        raw:
          type: object
          description: The raw userInfo object returned by the OAuth provider.
      description: OAuth adapter configuration options.
    ErrorDetailV1:
      type: object
      properties:
        field:
          type: string
          description: A reference to a field or parameter which cannot be processed.
        value:
          type: string
          description: The value which could not be processed.
        message:
          type: string
          description: A human readable message of error. Intended for developers.
      description: 'Additional information about the error '
    ErrorV1:
      required:
      - errorId
      - occurredAt
      type: object
      properties:
        errorId:
          type: string
          description: "An error identifier for the request, to be provided in troubleshooting."
        code:
          type: string
          description: |-
            An error code which describes this error. Documented per service and endpoint.
            See respective ErrorCodeRegistry DTO for possible error codes.
        message:
          type: string
          description: A human readable message of error. Intended for developers.
        details:
          type: array
          description: Additional information about the error which can be used in
            troubleshooting.
          items:
            $ref: "#/components/schemas/ErrorDetailV1"
        occurredAt:
          type: string
          description: The timestamp when the error occurred. This string is formatted
            according to RFC3339.
          format: date-time
    IamOauth2ErrorCodeRegistryV1:
      type: object
      properties:
        createApplicationOauth2TokenByAuthorizationCode:
          type: string
          enum:
          - INPUT_MALFORMED
          - INPUT_TOO_MANY_REQUESTS
          - AUTHENTICATION_FAILED
          - AUTHENTICATION_IDP_CONFIG_MALFORMED
        createApplicationOauth2TokenByRefreshToken:
          type: string
          enum:
          - INPUT_MALFORMED
          - INPUT_TOO_MANY_REQUESTS
          - AUTHENTICATION_FAILED
          - AUTHENTICATION_IDP_CONFIG_MALFORMED
        getApplicationOauth2UserInfo:
          type: string
          enum:
          - INPUT_MALFORMED
          - INPUT_TOO_MANY_REQUESTS
          - AUTHENTICATION_FAILED
          - AUTHENTICATION_IDP_CONFIG_MALFORMED
      description: |-
        This entry describes possible error codes that may be returned by their respective operation.
        These can be used to apply logic upon receiving an error response.
  responses:
    BadRequest:
      description: "The request is malformed, see error data for additional information"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorV1"
    Unauthorized:
      description: The request did not have valid authentication credentials
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorV1"
    Forbidden:
      description: The requester is not authorized to perform this action
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorV1"
    NotFound:
      description: The resource could not be found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorV1"
    Conflict:
      description: "The request could not be processed due to a conflict in state,\
        \ see error data for additional information"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorV1"
  parameters:
    Idp-Key:
      name: Idp-Key
      in: header
      required: true
      schema:
        maxLength: 64
        minLength: 1
        pattern: "^[a-zA-Z0-9-_.]{1,64}$"
        type: string
        description: An identity provider key which is used to identity a specific
          identity provider configuration.
        example: idp-1
    application-expression:
      name: application-expression
      in: path
      required: true
      schema:
        pattern: "^[a-zA-Z0-9-_.]{1,64}$"
        type: string
        description: "Used to identify a specific applicationId. The available options\
          \ are: \n* '{applicationId}' - direct applicationId reference"
  headers:
    Idp-Key:
      description: IdpKey to be used when matching given credentials for the current
        application idp configurations
      required: true
      schema:
        pattern: "^[a-zA-Z0-9-_.]{1,64}$"
        type: string
  securitySchemes:
    external-token:
      type: http
      scheme: bearer
      bearerFormat: External token issued by a trusted identity provider
    iam-console-token:
      type: http
      scheme: bearer
      bearerFormat: IAM issued jwt token for the IAM console application
    iam-tenant-token:
      type: http
      scheme: bearer
      bearerFormat: IAM issued jwt token for a generic application