swagger: "2.0"
info:
  title: Authentiq Connect API
  version: "1.0"
  description: |
    Authentiq Connect OAuth 2.0 and OpenID Connect API reference.
    Learn about [Authentiq ID](https://www.authentiq.com/) or check out the [Authentiq Connect](https://developers.authentiq.com) developer documentation.
  termsOfService: https://www.authentiq.com/terms
  contact:
    name: Team Authentiq
    url: https://www.authentiq.com/
    email: hello@authentiq.com
host: connect.authentiq.io
basePath: /
schemes:
  - https
consumes:
  - application/x-www-form-urlencoded
  - application/json
produces:
  - application/x-www-form-urlencoded
  - application/json
  - application/problem+json
  - text/html
paths:
  /authorize:
    get:
      summary: Authenticate a user
      description: |
        Start a session with Authentiq Connect to authenticate a user.

        ```
        GET https://connect.authentiq.io/authorize?client_id=<your-client-id>&response_type=code+id_token&scope=openid+email&redirect_uri=<your-redirect-uri>&state=0123456789
        ```

        This endpoint also supports the POST method.
      tags:
        - Authentication
      operationId: authorize
      parameters:
        - name: client_id
          in: query
          type: string
          description: >
            A client ID obtained from the [Dashboard](https://dashboard.authentiq.com/).
          required: true
        - name: response_type
          in: query
          type: string
          description: >
            The OIDC response type to use for this authentication flow. Valid choices are `code`, `id_token`, `token`, `token id_token`, `code id_token` `code token` and `code token id_token`, but a client can be configured with a more restricted set.
          required: true
        - name: scope
          in: query
          type: string
          description: >
            The space-separated identity claims to request from the end-user. Always include `openid` as a scope for compatibility with OIDC.
          required: true
        - name: redirect_uri
          in: query
          type: string
          description: >
            The location to redirect to after (un)successful authentication. See OIDC for the parameters passed in the query string (`response_mode=query`) or as fragments (`response_mode=fragment`). Unless the client is in test-mode this must be one of the registered redirect URLs.
          required: true
        - name: state
          in: query
          type: string
          description: >
            An opaque string that will be passed back to the redirect URL and therefore can be used to communicate client side state and prevent CSRF attacks.
          required: true
        - name: response_mode
          in: query
          type: string
          description: >
            Whether to append parameters to the redirect URL in the query string (`query`) or as fragments (`fragment`). This option usually has a sensible default for each of the response types.
          required: false
        - name: nonce
          in: query
          type: string
          description: >
            An nonce provided by the client (and opaque to Authentiq Connect) that will be included in any ID Token generated for this session. Clients should use the nonce to mitigate replay attacks.
          required: false
        - name: display
          in: query
          type: string
          description: >
            The authentication display mode, which can be one of `page`, `popup` or `modal`. Defaults to `page`.
          required: false
          default: page
        - name: prompt
          in: query
          type: string
          description: >
            Space-delimited, case sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for reauthentication and consent. The supported values are: `none`, `login`, `consent`. If `consent` the end-user is asked to (re)confirm what claims they share. Use `none` to check for an active session.
          required: false
          default: login
        - name: max_age
          in: query
          type: integer
          description: >
            Specifies the allowable elapsed time in seconds since the last time the end-user was actively authenticated.
          required: false
          default: 0
        - name: ui_locales
          in: query
          type: string
          description: >
            Specifies the preferred language to use on the authorization page, as a space-separated list of BCP47 language tags. Ignored at the moment.
          required: false
#        - in: query
#          name: id_token_hint
#          type: string
#          description: ""
#          required: false
#        - in: query
#          name: login_hint
#          type: string
#          description: ""
#          required: false
#        - in: query
#          name: acr_values
#          type: string
#          description: ""
#          required: false
      produces:
        - text/html
      responses:
        302:
          description: >
            A successful or erroneous authentication response.
        303:
          description: >
            *Sign in with Authentiq* page, popup or modal.
      externalDocs:
        description: OIDC Authorization Endpoint
        url: http://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint

  /token:
    post:
      summary: Obtain an ID Token
      description: |
        Exchange en authorization code for an ID Token or Access Token.

        This endpoint supports both `client_secret_basic` (default) and `client_secret_basic` authentication methods, as specified by the client's `token_endpoint_auth_method`.
      tags:
        - Authentication
      operationId: token
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - name: Authorization
          in: header
          description: >
            HTTP Basic authorization header.
          required: false
          type: string
        - name: client_id
          in: formData
          description: >
            The registered client ID.
          required: true
          type: string
        - name: client_secret
          in: formData
          description: >
            The registered client ID secret.
          required: true
          type: string
          format: password
        - name: grant_type
          in: formData
          description: >
            The authorization grant type, must be `authorization_code`.
          required: true
          type: string
        - name: code
          in: formData
          description: >
            The authorization code previously obtained from the Authentication endpoint.
          required: true
          type: string
        - name: redirect_uri
          in: formData
          description: >
            The redirect URL that was used previously with the Authentication endpoint.
          required: true
          type: string
      produces:
        - application/json
      responses:
        200:
          $ref: '#/responses/Token'
        400:
          $ref: '#/responses/OAuth2Error'
        401:
          $ref: '#/responses/OAuth2Error'
      externalDocs:
        description: OIDC Token Endpoint
        url: http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint

  /userinfo:
    get:
      summary: Retrieve a user profile
      tags:
        - Authentication
      description: |
        Use this endpoint to retrieve a user's profile in case you are unable to parse an ID Token or you've not already obtained enough details from the ID Token via the Token Endpoint.
      operationId: userInfo
      produces:
        - application/json
      responses:
        200:
          $ref: '#/responses/UserInfo'
        401:
          $ref: '#/responses/OAuth2Error'
        default:
          $ref: '#/responses/OAuth2Error'
      security:
        - oauth_code: [oidc, email, phone, address, aq:location, aq:name, aq:push]
        - oauth_implicit: [oidc, email, phone, address, aq:location, aq:name, aq:push]
      externalDocs:
        description: OIDC UserInfo Endpoint
        url: http://openid.net/specs/openid-connect-core-1_0.html#UserInfo

  /client:
    get:
      summary: List clients
      tags:
        - Client Management
      description: |
        Retrieve a list of clients.
      operationId: client
      produces:
        - application/json
      responses:
        200:
          description: A list of Client Objects.
          schema:
            type: array
            items:
              $ref: "#/definitions/Client"
        default:
          $ref: '#/responses/OAuth2Error'

      security:
        - client_registration_token: []
        - oauth_code: []
        - oauth_implicit: []

    post:
      summary: Register a client
      tags:
        - Client Management
      description: |
        Register a new client with this Authentiq Connect provider.

        This endpoint is compatible with [OIDC's Client Registration](http://openid.net/specs/openid-connect-registration-1_0.html) extension.

      operationId: createClient
      consumes:
        - application/json
        - multipart/form-data
      parameters:
        - $ref: '#/parameters/Client'
      responses:
        201:
          description: Client created
          headers:
            "Location":
              description: "URL of new client resource"
              type: string
        default:
          $ref: '#/responses/ProblemDetail'
      security:
        - client_registration_token: []
        - oauth_code: []
        - oauth_implicit: []
      externalDocs:
        description: OIDC Client Registration Endpoint
        url: http://openid.net/specs/openid-connect-registration-1_0.html#ClientRegistration


  /client/{client_id}:
    get:
      summary: View a client
      tags:
        - Client Management
      description: |
        Retrieve the configuration of a previously registered client.
      operationId: getClient
      produces:
        - application/json
      parameters:
        - $ref: "#/parameters/client_id"
      responses:
        "200":
          description: Client found
          schema:
            $ref: "#/definitions/Client"
        default:
          $ref: '#/responses/OAuth2Error'
      security:
        - client_registration_token: []
        - oauth_code: []
        - oauth_implicit: []
      externalDocs:
        description: OIDC Client Configuration Endpoint
        url: http://openid.net/specs/openid-connect-registration-1_0.html#ClientConfigurationEndpoint

    put:
      summary: Update a client
      tags:
        - Client Management
      description: |
        Update the configuration of a previously registered client.
      operationId: updateClient
      consumes:
        - application/json
        - multipart/form-data
      produces:
        - application/json
      parameters:
        - $ref: "#/parameters/client_id"
        - $ref: "#/parameters/Client"
      responses:
        "200":
          description: Client updated
          schema:
            $ref: "#/definitions/Client"
        default:
          $ref: '#/responses/ProblemDetail'
      security:
        - client_registration_token: []
        - oauth_code: []
        - oauth_implicit: []
      externalDocs:
        description: OIDC Client Configuration Endpoint
        url: http://openid.net/specs/openid-connect-registration-1_0.html#ClientConfigurationEndpoint

    delete:
      summary: Delete a client
      tags:
        - Client Management
      description: |
        Delete a previously registered client.
      operationId: clientClient_id
      parameters:
        - $ref: "#/parameters/client_id"
      responses:
        "204":
          description: Client deleted
        default:
          $ref: '#/responses/ProblemDetail'
      security:
        - client_registration_token: []
        - oauth_code: []
        - oauth_implicit: []
      externalDocs:
        description: OIDC Client Configuration Endpoint
        url: http://openid.net/specs/openid-connect-registration-1_0.html#ClientConfigurationEndpoint

  /{client_id}/iframe:
    get:
      tags:
        - Session Management
      summary: Include a session iframe
      description: |
        An OpenID Connect Session Management iframe to facilitate e.g. single sign-on or remote logouts.

        The iframe implements the OIDC postMessage-based [change notification protocol](http://openid.net/specs/openid-connect-session-1_0.html#ChangeNotification) via which a client can receive notifications about session state changes.
      operationId: authorizeIframe
      parameters:
        - $ref: '#/parameters/client_id'
      produces:
        - test/html
      responses:
        200:
          description: OK
          headers:
            "Cache-Control":
              description: public, max-age=7200
              type: string
      externalDocs:
        description: OIDC OP Session Management Iframe
        url: http://openid.net/specs/openid-connect-session-1_0.html#OPiframe


definitions:
  Token:
    description: >
      Successful token response
    required:
      - token_type
    properties:
      token_type:
        type: string
      access_token:
        description: The access token issued by the authorization server.
        type: string
      id_token:
        description: ID Token value associated with the authenticated session.
        type: string
      refresh_token:
        description: The refresh token issued to the client, if any.
        type: string
      expires_in:
        description: The lifetime in seconds of the access token.
        type: integer
        format: int32
      expires_at:
        description: The time the access token will expire in seconds since epoch.
        type: integer
        format: int64
      scope:
        description: The scope of the granted tokens.
        type: string

  OAuth2Error:
    description: >
      Error Response defined as in Section 5.2 of OAuth 2.0 [RFC6749].
    required:
    - error
    properties:
      error:
        type: string
      error_description:
        type: string

  ProblemDetail:
    description: >
      HTTP Problem Detail
    required:
      - type
      - status
    properties:
      type:
        type: string
        default: about:blank
      title:
        type: string
        description: >
          Human-readable summary of the problem type.
      status:
        type: integer
        description: >
          The HTTP status code for this occurrence of the problem.
      detail:
        type: string
        description: >
          Human-readable explanation specific to this occurrence of the problem.

  Session:
    description: "Session object"
    properties:
      version:
        type: integer
      sub:
        type: string
      session_id:
        type: string
      session_state:
        type: string
      session_uri:
        type: string
      client_id:
        type: string
      scopes:
        type: array
        items:
          type: string
      scopes_optional:
        type: array
        items:
          type: string
      scopes_required:
        type: array
        items:
          type: string
      scopes_signed:
        type: array
        items:
          type: string
      tokens_seen:
        type: array
        items:
          type: string
      scopes_seen:
        type: array
        items:
          type: string
      redirect_uri:
        type: string
      response_type:
        type: string
      response_mode:
        type: string
      nonce:
        type: string
      created_at:
        type: string
      connected_at:
        type: string
        format: date-time
      authenticated_at:
        type: string
        format: date-time
      concluded_at:
        type: string
        format: date-time
      deleted_at:
        type: string
        format: date-time
      client_name:
        type: string
      client_uri:
        type: string
      logo_uri:
        type: string
      policy_uri:
        type: string
      tos_uri:
        type: string
      contacts:
        type: array
        items:
          type: string

  UserInfo:
    description: OIDC UserInfo structure
    required:
      - sub
    properties:
      sub:
        type: string
      name:
        type: string
      given_name:
        type: string
      family_name:
        type: string
      email:
        type: string
      email_verified:
        type: boolean
      phone_number:
        type: string
      phone_number_verified:
        type: boolean
      address:
        $ref: "#/definitions/Address"
      aq:location:
        description: Geolocation structure
        properties:
          latitude:
            type: number
            format: float
          longitude:
            type: number
            format: float
          address:
            $ref: "#/definitions/Address"

  Address:
    description: OIDC Address structure
    properties:
      street_address:
        type: string
      locality:
        type: string
      region:
        type: string
      postal_code:
        type: string
      country:
        type: string

  Client:
    description: Client object
    required:
      - client_name
      - client_uri
    properties:
      client_id:
        type: string # only in responses
      redirect_uris:
        type: array
        items:
          type: string
      response_types:
        type: array
        items:
          type: string
      grant_types:
        type: array
        items:
          type: string
      application_type:
        type: string
      contacts:
        type: array
        items:
          type: string
      client_name:
        type: string
      logo_uri:
        type: string
      client_uri:
        type: string
      policy_uri:
        type: string
      tos_uri:
        type: string
      default_max_age:
        type: integer
        format: int64
      default_scopes:
        type: array
        items:
          type: string


parameters:
  Client:
    name: body
    in: body
    description: Client Object
    required: true
    schema:
      $ref: "#/definitions/Client"

  client_id:
    name: client_id
    in: path
    description: Client identifier
    required: true
    type: string


responses:
  Token:
    description: Token response
    schema:
      $ref: "#/definitions/Token"
  UserInfo:
    description: UserInfo response
    schema:
      $ref: "#/definitions/UserInfo"
  OAuth2Error:
    description: OAuth 2.0 error response
    schema:
      $ref: '#/definitions/OAuth2Error'
  ProblemDetail:
    description: Problem Detail error response
    schema:
      $ref: '#/definitions/ProblemDetail'


securityDefinitions:
  client_secret:
    description: Session management by confidential clients.
    type: oauth2
    flow: password
    tokenUrl: https://connect.authentiq.io/token
    scopes:
      clients: Enable client management
  client_registration_token:
    description: Client management via registration token.
    type: apiKey
    name: Authorization
    in: header
  user_jwt:
    description: Session management by Authentiq ID.
    type: oauth2
    flow: application
    tokenUrl: https://connect.authentiq.io/token
    scopes:
      session: Enable session management
  oauth_code:
    description: End-user authentication.
    type: oauth2
    flow: accessCode
    authorizationUrl: https://connect.authentiq.io/authorize
    tokenUrl: https://connect.authentiq.io/token
    scopes:
      oidc: Enable OIDC flow
      email: The user's email address
      phone: The user's phone number
      address: The user's postal address
      aq:location: The user's current location
      aq:name: The user's full name
      aq:push: Enable *One click sign-in*
  oauth_implicit:
    description: End-user authentication.
    type: oauth2
    flow: implicit
    authorizationUrl: https://connect.authentiq.io/authorize
    scopes:
      oidc: Enable OIDC flow
      email: The user's email address
      phone: The user's phone number
      address: The user's postal address
      aq:location: The user's current location
      aq:name: The user's full name
      aq:push: Enable *One click sign-in*

#tags:
#  - authentiq
#  - oauth2
#  - oidc
#  - oidc-client-registration
#  - oidc-discovery
#  - oidc-session-management
#  - oidc-backchannel-logout

externalDocs:
  description: Authentiq Developer Docs
  url: https://developers.authentiq.com/