openapi: 3.1.0
info:
  contact:
    name: Engity
    url: https://engity.com
  description: The Engity IdP is a OpenID Connect complaint Identity Provider. This
    API provides access to functions for end-users but also for services to interact
    with this IdP.
  termsOfService: https://engity.com/terms/
  title: Engity IdP
  version: 1.0.23
servers:
- description: Default Format
  url: https://{host}{subPath}
  variables:
    host:
      default: id.demo.engity.app
      description: This represents the `host` an Engity's directory instance is bound
        to.
    subPath:
      default: ""
      description: This represents a `subPath` an Engity's directory instance is bound
        to, if any. This is optional, but must start with `/`.
paths:
  /resources/{name}:
    get:
      description: Returns the content of the provided global resource together with
        all relevant headers ready to be used inside of a browser.
      operationId: getGlobalResource
      parameters:
      - description: Provides the actual revision of the global resource. This is
          required to optimize the caching mechanism of the browsers, ensure that
          several resources of the same name can be loaded of different revisions
          and also prevent bot guessing.
        in: query
        name: revision
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/IfNonMatchHeader'
      responses:
        "200":
          content:
            '*/*':
              schema:
                format: binary
                type: string
          description: Resource found
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
              style: simple
            Content-Type:
              $ref: '#/components/headers/ContentType'
              style: simple
            ETag:
              $ref: '#/components/headers/ETag'
              style: simple
            Last-Modified:
              $ref: '#/components/headers/LastModified'
              style: simple
        "304":
          description: Resource not modified
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
              style: simple
            Content-Type:
              $ref: '#/components/headers/ContentType'
              style: simple
            ETag:
              $ref: '#/components/headers/ETag'
              style: simple
            Last-Modified:
              $ref: '#/components/headers/LastModified'
              style: simple
        "404":
          description: Resource not found
      summary: Get resource
      tags:
      - resources
      - clients
    parameters:
    - example: finch/main.css
      in: path
      name: name
      required: true
      schema:
        type: string
  /v1/.well-known/directory-configuration:
    get:
      description: Holds the configuration descriptor of the current Engity directory.
      operationId: getDescriptorsDirectory
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Directory'
          description: Successful operation
      summary: Get Directory descriptor
      tags:
      - oidc
      - clients
      - services
  /v1/.well-known/openid-configuration:
    get:
      description: Holds the OpenID Connect Discovery content. See [official specs](https://openid.net/specs/openid-connect-discovery-1_0.html)
        for more information.
      operationId: getDescriptorsOpenIdConfiguration
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenIdConnectConfiguration'
          description: Successful operation
      summary: Get OpenID Connect configuration
      tags:
      - oidc
      - clients
      - services
  /v1/jwks.json:
    get:
      description: Returns the JSON Wek Keys (JWK) assigned manged by this repository.
        See [official specs](https://openid.net/specs/openid-connect-discovery-1_0-21.html#JWK)
        for more information.
      operationId: getDescriptorsJwks
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Jwks'
          description: Successful operation
      summary: Get JSON Wek Keys
      tags:
      - oidc
      - oauth2
      - clients
      - services
  /v1/localization:
    get:
      description: Returns a map of all messages of the current directory, matching
        the requested `Accept-Language` header.
      operationId: getLocalization
      parameters:
      - $ref: '#/components/parameters/IfNonMatchHeader'
      - $ref: '#/components/parameters/AcceptLanguage'
      - description: Tells the server to retrieve the localization as a `script` which
          can be included via a script-tag inside of a browser or as a simple JSON
          (if absent or `json`). This features is explicitly via query parameter and
          NOT via `Accept` headers, because browsers usually do only send `*/*` as
          accept header if they're requesting a resource via script-tag.
        in: query
        name: format
        schema:
          default: json
          enum:
          - script
          - json
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Localization'
            text/javascript:
              schema:
                examples:
                - if (!window.Engity)window.Engity = {};window.Engity.localization
                  = {...}
                type: string
          description: Resource found
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
              style: simple
            Content-Type:
              $ref: '#/components/headers/ContentType'
              style: simple
            ETag:
              $ref: '#/components/headers/ETag'
              style: simple
            Last-Modified:
              $ref: '#/components/headers/LastModified'
              style: simple
        "304":
          description: Resource not modified
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
              style: simple
            Content-Type:
              $ref: '#/components/headers/ContentType'
              style: simple
            ETag:
              $ref: '#/components/headers/ETag'
              style: simple
            Last-Modified:
              $ref: '#/components/headers/LastModified'
              style: simple
        "404":
          description: Resource not found
      summary: Get all localized directory's messages
      tags:
      - resources
      - clients
  /v1/resources/{name}:
    get:
      description: Returns the content of the provided organization owned resource
        together with all relevant headers ready to be used inside of a browser.
      operationId: getResource
      parameters:
      - description: Provides the actual revision of the resource. This is required
          to optimize the caching mechanism of the browsers, ensure that several resources
          of the same name can be loaded of different revisions and also prevent bot
          guessing.
        in: query
        name: revision
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/IfNonMatchHeader'
      responses:
        "200":
          content:
            '*/*':
              schema:
                format: binary
                type: string
          description: Resource found
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
              style: simple
            Content-Type:
              $ref: '#/components/headers/ContentType'
              style: simple
            ETag:
              $ref: '#/components/headers/ETag'
              style: simple
            Last-Modified:
              $ref: '#/components/headers/LastModified'
              style: simple
        "304":
          description: Resource not modified
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
              style: simple
            Content-Type:
              $ref: '#/components/headers/ContentType'
              style: simple
            ETag:
              $ref: '#/components/headers/ETag'
              style: simple
            Last-Modified:
              $ref: '#/components/headers/LastModified'
              style: simple
        "404":
          description: Resource not found
      summary: Get global resource
      tags:
      - resources
      - clients
    parameters:
    - example: finch/main.css
      in: path
      name: name
      required: true
      schema:
        type: string
  /v1/user:
    delete:
      description: Delete all users the requesting service has access to and that
        are matching the requirements.
      operationId: deleteUsers
      parameters:
      - description: Because this method is so destructive, this parameter has always
          be provided to really perform the deletion. It needs always be true, otherwise
          the operations fails.
        in: query
        name: force
        required: true
        schema:
          default: false
          type: boolean
      - description: If provided only users matching these IDs will be returned.
        in: query
        name: id
        required: false
        schema:
          items:
            $ref: '#/components/schemas/Uuid'
          type: array
      - description: If provided only users matching these names will be returned.
          Names could match usernames but also contacts that are identifying this
          user.
        in: query
        name: name
        required: false
        schema:
          items:
            examples:
            - foo@example.com
            type: string
          type: array
      responses:
        "204":
          $ref: '#/components/responses/PlainSuccess'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
      security:
      - service_key: []
      summary: Delete all users
      tags:
      - user
      - services
    get:
      description: Returns all users the requesting service has access to and that
        are matching the requirements.
      operationId: getUsers
      parameters:
      - description: If provided only users matching these IDs will be returned.
        in: query
        name: id
        required: false
        schema:
          items:
            $ref: '#/components/schemas/Uuid'
          type: array
      - description: If provided only users matching these names will be returned.
          Names could match usernames but also contacts that are identifying this
          user.
        in: query
        name: name
        required: false
        schema:
          items:
            examples:
            - foo@example.com
            type: string
          type: array
      responses:
        "200":
          $ref: '#/components/responses/Users'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
      security:
      - service_key: []
      summary: Get all users
      tags:
      - user
      - services
    put:
      description: Creates a new user with the given details.
      operationId: createUser
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRequirement'
        required: true
      responses:
        "200":
          $ref: '#/components/responses/User'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
        "422":
          $ref: '#/components/responses/PlainUnprocessableEntity'
      security:
      - service_key: []
      summary: Creates a new user
      tags:
      - user
      - services
  /v1/user/{id}:
    delete:
      description: Delete the given user by its ID. This function might not be supported
        in for all directories/environments.
      operationId: deleteUser
      parameters:
      - in: path
        name: id
        required: true
        schema:
          $ref: '#/components/schemas/Uuid'
      responses:
        "204":
          $ref: '#/components/responses/PlainSuccess'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
        "404":
          $ref: '#/components/responses/PlainNotFound'
      security:
      - service_key: []
      summary: Deletes the user by its ID
      tags:
      - user
      - services
    get:
      description: Returns the details of the user by its ID.
      operationId: getUser
      parameters:
      - in: path
        name: id
        required: true
        schema:
          $ref: '#/components/schemas/Uuid'
      responses:
        "200":
          $ref: '#/components/responses/User'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
        "404":
          $ref: '#/components/responses/PlainNotFound'
      security:
      - service_key: []
      summary: Get user details
      tags:
      - user
      - services
  /v1/user/{id}/contact:
    get:
      description: Returns all the fields of the user by ids ID.
      operationId: getAllContactsOfUser
      parameters:
      - in: path
        name: id
        required: true
        schema:
          $ref: '#/components/schemas/Uuid'
      responses:
        "200":
          $ref: '#/components/responses/ContactAssignments'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
        "404":
          $ref: '#/components/responses/PlainNotFound'
      security:
      - service_key: []
      summary: Get all fields of user
      tags:
      - user
      - clients
      - contacts
    put:
      description: Creates a contact of a user by its ID.
      operationId: createContactOfUser
      parameters:
      - in: path
        name: id
        required: true
        schema:
          $ref: '#/components/schemas/Uuid'
      requestBody:
        $ref: '#/components/requestBodies/CreateContact'
      responses:
        "200":
          $ref: '#/components/responses/CreateContact'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
      security:
      - service_key: []
      summary: Creates contact of user
      tags:
      - user
      - clients
      - contacts
  /v1/user/{id}/contact/{type}/{value}:
    delete:
      description: Deletes a contact by `type` and `value` of the user by its ID.
      operationId: deleteContactOfUser
      parameters:
      - in: path
        name: id
        required: true
        schema:
          $ref: '#/components/schemas/Uuid'
      - in: path
        name: type
        required: true
        schema:
          $ref: '#/components/schemas/ContactType'
      - in: path
        name: value
        required: true
        schema:
          type: string
      responses:
        "204":
          $ref: '#/components/responses/PlainSuccess'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
      security:
      - service_key: []
      summary: Delete contact of user
      tags:
      - user
      - clients
      - contacts
  /v1/user/{id}/field:
    get:
      description: Returns all the fields of the user by its ID.
      operationId: getAllFieldsOfUser
      parameters:
      - in: path
        name: id
        required: true
        schema:
          $ref: '#/components/schemas/Uuid'
      responses:
        "200":
          $ref: '#/components/responses/Fields'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
        "404":
          $ref: '#/components/responses/PlainNotFound'
      security:
      - service_key: []
      summary: Get all fields of user
      tags:
      - user
      - services
      - fields
    post:
      description: Set all the fields of the user by its ID.
      operationId: setAllFieldsOfUser
      parameters:
      - in: path
        name: id
        required: true
        schema:
          $ref: '#/components/schemas/Uuid'
      requestBody:
        $ref: '#/components/requestBodies/Fields'
      responses:
        "204":
          $ref: '#/components/responses/PlainSuccess'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
        "404":
          $ref: '#/components/responses/PlainNotFound'
      security:
      - service_key: []
      summary: Set all fields of user
      tags:
      - user
      - services
      - fields
  /v1/user/{id}/field/{name}:
    delete:
      description: Delete named field of the user by its ID.
      operationId: deleteFieldOfUser
      parameters:
      - in: path
        name: id
        required: true
        schema:
          $ref: '#/components/schemas/Uuid'
      - in: path
        name: name
        required: true
        schema:
          $ref: '#/components/schemas/Key'
      responses:
        "204":
          $ref: '#/components/responses/PlainSuccess'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
        "404":
          $ref: '#/components/responses/PlainNotFound'
      security:
      - service_key: []
      summary: Delete named field of user
      tags:
      - user
      - services
      - fields
    get:
      description: Returns a named field of the user by its ID.
      operationId: getFieldOfUser
      parameters:
      - in: path
        name: id
        required: true
        schema:
          $ref: '#/components/schemas/Uuid'
      - in: path
        name: name
        required: true
        schema:
          $ref: '#/components/schemas/Key'
      responses:
        "200":
          $ref: '#/components/responses/FieldValue'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
        "404":
          $ref: '#/components/responses/PlainNotFound'
      security:
      - service_key: []
      summary: Get named field of user
      tags:
      - user
      - services
      - fields
    post:
      description: Set named field of the user by its ID.
      operationId: setFieldOfUser
      parameters:
      - in: path
        name: id
        required: true
        schema:
          $ref: '#/components/schemas/Uuid'
      - in: path
        name: name
        required: true
        schema:
          $ref: '#/components/schemas/Key'
      requestBody:
        $ref: '#/components/requestBodies/FieldValue'
      responses:
        "204":
          $ref: '#/components/responses/PlainSuccess'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
        "404":
          $ref: '#/components/responses/PlainNotFound'
      security:
      - service_key: []
      summary: Set named field of user
      tags:
      - user
      - services
      - fields
  /v1/user/current:
    delete:
      description: Gives the user the possibility to delete itself. This function
        might not be supported in for all directories/environments.
      operationId: deleteCurrentUser
      responses:
        "204":
          $ref: '#/components/responses/PlainSuccess'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
      security:
      - client_oidc:
        - profile
      summary: Deletes the current user
      tags:
      - user
      - clients
    get:
      description: Returns the details of the current user.
      operationId: getCurrentUser
      responses:
        "200":
          $ref: '#/components/responses/User'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
      security:
      - client_oidc:
        - profile
      summary: Get current user details
      tags:
      - user
      - clients
  /v1/user/current/contact:
    get:
      description: Returns all the fields of the current user.
      operationId: getAllContactsOfCurrentUser
      responses:
        "200":
          $ref: '#/components/responses/ContactAssignments'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
      security:
      - client_oidc:
        - profile
      summary: Get all fields of current user
      tags:
      - user
      - clients
      - contacts
  /v1/user/current/contact/verify/trigger:
    put:
      description: Triggers for the current user the verify of the given contact.
        If the contact was able to currently be validated, the contact will be added
        to the user.
      operationId: triggerContactVerifyOfCurrentUser
      requestBody:
        $ref: '#/components/requestBodies/TriggerContactVerify'
      responses:
        "200":
          $ref: '#/components/responses/TriggerContactVerify'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
      security:
      - client_oidc:
        - profile
      summary: Triggers contact verify of current user
      tags:
      - user
      - clients
      - contacts
  /v1/user/current/field:
    get:
      description: Returns all the fields of the current user.
      operationId: getAllFieldsOfCurrentUser
      responses:
        "200":
          $ref: '#/components/responses/Fields'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
      security:
      - client_oidc:
        - profile
      summary: Get all fields of current user
      tags:
      - user
      - clients
      - fields
    post:
      description: Set all the fields of the current user.
      operationId: setAllFieldsOfCurrentUser
      requestBody:
        $ref: '#/components/requestBodies/Fields'
      responses:
        "204":
          $ref: '#/components/responses/PlainSuccess'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
      security:
      - client_oidc:
        - profile
      summary: Set all fields of current user
      tags:
      - user
      - clients
      - fields
  /v1/user/current/field/{name}:
    delete:
      description: Deletes the named field of the current user.
      operationId: deleteFieldOfCurrentUser
      parameters:
      - in: path
        name: name
        required: true
        schema:
          $ref: '#/components/schemas/Key'
      responses:
        "204":
          $ref: '#/components/responses/PlainSuccess'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
        "404":
          $ref: '#/components/responses/PlainNotFound'
      security:
      - client_oidc:
        - profile
      summary: Delete named field of current user
      tags:
      - user
      - clients
      - fields
    get:
      description: Returns a named field of the current user.
      operationId: getFieldOfCurrentUser
      parameters:
      - in: path
        name: name
        required: true
        schema:
          $ref: '#/components/schemas/Key'
      responses:
        "200":
          $ref: '#/components/responses/FieldValue'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
        "404":
          $ref: '#/components/responses/PlainNotFound'
      security:
      - client_oidc:
        - profile
      summary: Get named field of current user details
      tags:
      - user
      - clients
      - fields
    post:
      description: Set the named field of the current user.
      operationId: setFieldOfCurrentUser
      parameters:
      - in: path
        name: name
        required: true
        schema:
          $ref: '#/components/schemas/Key'
      requestBody:
        $ref: '#/components/requestBodies/FieldValue'
      responses:
        "204":
          $ref: '#/components/responses/PlainSuccess'
        "401":
          $ref: '#/components/responses/PlainUnauthorized'
        "403":
          $ref: '#/components/responses/PlainForbidden'
        "404":
          $ref: '#/components/responses/PlainNotFound'
      security:
      - client_oidc:
        - profile
      summary: Set named field of current user
      tags:
      - user
      - clients
      - fields
components:
  headers:
    CacheControl:
      description: Tells to browser if and how caching of the retrieved resource it
        allowed. [See MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control).
      schema:
        examples:
        - max-age=31536000, public
        type: string
      style: simple
    ContentType:
      description: What is the content type of the actual returned resource. [See
        MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type).
      schema:
        examples:
        - image/jpeg
        type: string
      style: simple
    ETag:
      description: Identifies a specific version of the returned resource. It is mostly
        used by communication between servers and browser to reduce the amounts the
        clients has to download the full file of the content hasn't change since the
        last retrieval. [See MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag).
      schema:
        examples:
        - 3488741ad816033e1e4b09999d785aba
        type: string
      style: simple
    LastModified:
      description: When was the resource modified the last time. [See MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified).
      schema:
        examples:
        - Wed, 21 Oct 2015 07:28:00 GMT
        type: string
      style: simple
  parameters:
    AcceptLanguage:
      description: Tells the server which languages are accepted by the browser. The
        server will select the best fitting localized version of the requested content
        based on this. [See MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language)
      in: header
      name: Accept-Language
      schema:
        examples:
        - fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5
        type: string
    IfNonMatchHeader:
      description: Tells the server what is the current cached version of the client.
        It is mostly used by communication between servers and browser to reduce the
        amounts the clients has to download the full file of the content hasn't change
        since the last retrieval. [See MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-None-Match).
      in: header
      name: If-None-Match
      schema:
        examples:
        - 3488741ad816033e1e4b09999d785aba
        type: string
  requestBodies:
    CreateContact:
      content:
        application/json:
          schema:
            properties:
              contact:
                $ref: '#/components/schemas/ContactAssignmentRequest'
              teleApproval:
                $ref: '#/components/schemas/TriggerTeleApprovalRequest'
            type: object
    FieldValue:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FieldValue'
    Fields:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Fields'
    TriggerContactVerify:
      content:
        application/json:
          schema:
            properties:
              contact:
                $ref: '#/components/schemas/Contact'
              teleApproval:
                $ref: '#/components/schemas/TriggerTeleApprovalRequest'
            type: object
  responses:
    ContactAssignment:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ContactAssignment'
      description: Contact assignment found
    ContactAssignments:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ContactAssignments'
      description: Contact assignments found
    CreateContact:
      content:
        application/json:
          schema:
            properties:
              teleApproval:
                $ref: '#/components/schemas/TriggerTeleApprovalResponse'
            type: object
      description: Contact was created
    FieldValue:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FieldValue'
      description: Field found
    Fields:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Fields'
      description: Fields to be set
    PlainBadRequest:
      description: Bad request
    PlainForbidden:
      description: Forbidden
    PlainNotFound:
      description: Resource not found
    PlainSuccess:
      description: Success
    PlainUnauthorized:
      description: Unauthorized
    PlainUnprocessableEntity:
      description: Unprocessable entity
    TriggerContactVerify:
      content:
        application/json:
          schema:
            properties:
              teleApproval:
                $ref: '#/components/schemas/TriggerTeleApprovalResponse'
            type: object
      description: Verify of contact triggered
    User:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'
        application/json+full:
          schema:
            $ref: '#/components/schemas/User'
        application/json+short:
          schema:
            $ref: '#/components/schemas/UserShort'
      description: User found
    Users:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Users'
        application/json+full:
          schema:
            $ref: '#/components/schemas/Users'
        application/json+short:
          schema:
            $ref: '#/components/schemas/UserShorts'
      description: Users found
  schemas:
    Authorization:
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        key:
          $ref: '#/components/schemas/StructuredKey'
        resource:
          format: uri
          type: string
        title:
          examples:
          - Google
          type: string
        type:
          $ref: '#/components/schemas/AuthorizationType'
      required:
      - id
      - type
      - key
      - title
      type: object
    AuthorizationType:
      enum:
      - oidc
      type: string
    Authorizations:
      items:
        $ref: '#/components/schemas/Authorization'
      type: array
    Claim:
      examples:
      - family_name
      - given_name
      - email
      - nickname
      format: regex
      pattern: '[a-zA-Z][a-zA-Z0-9]*(_[a-zA-Z][a-zA-Z0-9]*)*'
      type: string
    Contact:
      discriminator:
        mapping:
          emailAddress: '#/components/schemas/ContactEmailAddress'
          phoneNumber: '#/components/schemas/ContactPhoneNumber'
        propertyName: type
      oneOf:
      - $ref: '#/components/schemas/ContactEmailAddress'
      - $ref: '#/components/schemas/ContactPhoneNumber'
      required:
      - type
      type: object
    ContactAssignment:
      properties:
        classification:
          $ref: '#/components/schemas/ContactClassification'
        contact:
          $ref: '#/components/schemas/Contact'
        state:
          $ref: '#/components/schemas/ContactState'
      required:
      - contact
      type: object
    ContactAssignmentRequest:
      properties:
        classification:
          $ref: '#/components/schemas/ContactClassification'
        contact:
          $ref: '#/components/schemas/Contact'
      required:
      - contact
      type: object
    ContactAssignments:
      examples:
      - - classification: primary
          state: verified
          type: emailAddress
          value: foo@example.com
        - state: unverified
          type: emailAddress
          value: bar@example.com
        - state: verified
          type: phoneNumber
          value: "+4930123456789"
      items:
        $ref: '#/components/schemas/ContactAssignment'
      type: array
    ContactClassification:
      enum:
      - default
      - primary
      type: string
    ContactClassificationPermit:
      enum:
      - forbidden
      - allowed
      - required
      examples:
      - allowed
      - required
      type: string
    ContactClassificationSpec:
      properties:
        loginAllowed:
          default: false
          type: boolean
        permit:
          $ref: '#/components/schemas/ContactClassificationPermit'
      required:
      - permit
      type: object
    ContactClassificationSpecs:
      properties:
        default:
          $ref: '#/components/schemas/ContactClassificationSpec'
        primary:
          $ref: '#/components/schemas/ContactClassificationSpec'
      type: object
    ContactEmailAddress:
      examples:
      - type: emailAddress
        value: foo@bar.com
      properties:
        type:
          default: emailAddress
          enum:
          - emailAddress
          type: string
        value:
          $ref: '#/components/schemas/EmailAddress'
      required:
      - type
      - value
      type: object
    ContactPhoneNumber:
      properties:
        type:
          default: phoneNumber
          enum:
          - phoneNumber
          type: string
        value:
          $ref: '#/components/schemas/PhoneNumber'
      required:
      - type
      - value
      type: object
    ContactSpec:
      properties:
        classifications:
          $ref: '#/components/schemas/ContactClassificationSpecs'
        maxOccurrences:
          examples:
          - 50
          maximum: 65535
          minimum: 0
          type: integer
        minOccurrences:
          examples:
          - 0
          maximum: 65535
          minimum: 0
          type: integer
      required:
      - classifications
      type: object
    ContactSpecs:
      properties:
        emailAddress:
          $ref: '#/components/schemas/ContactSpec'
        phoneNumber:
          $ref: '#/components/schemas/ContactSpec'
      type: object
    ContactState:
      enum:
      - unverified
      - verified
      examples:
      - verified
      - unverified
      type: string
    ContactType:
      enum:
      - emailAddress
      - phoneNumber
      type: string
    CryptoKeyCurve:
      enum:
      - P-256
      - P-384
      - P-521
      - Ed25519
      examples:
      - Ed25519
      - P-521
      type: string
    CryptoKeyType:
      enum:
      - RSA
      - EC
      - OKP
      examples:
      - EC
      - OKP
      - RSA
      type: string
    DateTime:
      description: Representation of a date and time object as RFC3339, optionally
        with milli seconds.
      format: date-time
      type: string
    Directory:
      description: Represents the base data of an Engity directory together with it's
        specifications.
      properties:
        assignment:
          $ref: '#/components/schemas/DirectoryAssignment'
        authorizations:
          $ref: '#/components/schemas/Authorizations'
        createdAt:
          $ref: '#/components/schemas/DateTime'
        id:
          $ref: '#/components/schemas/Uuid'
        key:
          $ref: '#/components/schemas/StructuredKey'
        lastModifiedAt:
          $ref: '#/components/schemas/DateTime'
        spec:
          $ref: '#/components/schemas/DirectorySpec'
        state:
          $ref: '#/components/schemas/DirectoryState'
        title:
          examples:
          - Foo Directory
          type: string
        urls:
          $ref: '#/components/schemas/DirectoryUrls'
      required:
      - id
      - createdAt
      - lastModifiedAt
      - key
      - title
      type: object
    DirectoryAssignment:
      description: 'Assigns a directory to a URL base as follows: `https://<host>[/<subPath>]`'
      properties:
        host:
          format: hostname
          type: string
        subPath:
          $ref: '#/components/schemas/SubPath'
      required:
      - host
      type: object
    DirectorySpec:
      description: Defines the basic rules of a directory, supported features and
        its behavior.
      properties:
        contacts:
          $ref: '#/components/schemas/ContactSpecs'
        fields:
          $ref: '#/components/schemas/FieldGroups'
        password:
          $ref: '#/components/schemas/PasswordSpec'
        username:
          $ref: '#/components/schemas/UsernameSpec'
      type: object
    DirectoryState:
      enum:
      - disabled
      - enabled
      - deleted
      examples:
      - enabled
      type: string
    DirectoryUrls:
      properties:
        afterLogin:
          examples:
          - https://demo.engity.app/after-login
          format: uri
          type: string
        afterLogout:
          examples:
          - https://demo.engity.app/after-logout
          format: uri
          type: string
        afterPasswordReset:
          examples:
          - https://demo.engity.app/after-password-reset
          format: uri
          type: string
        afterSignup:
          examples:
          - https://demo.engity.app/after-signup
          format: uri
          type: string
        afterVerifyContact:
          examples:
          - https://demo.engity.app/after-verify-contact
          format: uri
          type: string
        afterVerifyContactFailed:
          examples:
          - https://demo.engity.app/after-verify-contact-failed
          format: uri
          type: string
        default:
          examples:
          - https://demo.engity.app/
          format: uri
          type: string
      type: object
    EmailAddress:
      enum:
      - foo@bar.com
      type: string
    FieldGroup:
      properties:
        fields:
          items:
            $ref: '#/components/schemas/FieldSpec'
          type: array
        key:
          $ref: '#/components/schemas/Key'
        priority:
          $ref: '#/components/schemas/Priority'
        title:
          examples:
          - Group A
          type: string
      required:
      - key
      - title
      type: object
    FieldGroups:
      items:
        $ref: '#/components/schemas/FieldGroup'
      type: array
    FieldSpec:
      properties:
        key:
          $ref: '#/components/schemas/Key'
        priority:
          $ref: '#/components/schemas/Priority'
        required:
          default: false
          type: boolean
        title:
          examples:
          - Field A
          type: string
        type:
          $ref: '#/components/schemas/FieldType'
      required:
      - key
      - type
      - title
      type: object
    FieldType:
      enum:
      - unknown
      - text
      - integer
      examples:
      - text
      - integer
      type: string
    FieldValue:
      discriminator:
        mapping:
          integer: '#/components/schemas/FieldValueInteger'
          text: '#/components/schemas/FieldValueText'
          unknown: '#/components/schemas/FieldValueUnknown'
        propertyName: type
      examples:
      - type: text
        value: fooBar
      - type: integer
        value: 123
      oneOf:
      - $ref: '#/components/schemas/FieldValueUnknown'
      - $ref: '#/components/schemas/FieldValueText'
      - $ref: '#/components/schemas/FieldValueInteger'
      required:
      - type
      type: object
    FieldValueInteger:
      properties:
        type:
          default: integer
          enum:
          - integer
          type: string
        value:
          type: integer
      required:
      - type
      type: object
    FieldValueText:
      properties:
        type:
          default: text
          enum:
          - text
          type: string
        value:
          type: string
      required:
      - type
      type: object
    FieldValueUnknown:
      properties:
        type:
          default: unknown
          enum:
          - unknown
          type: string
      required:
      - type
      type: object
    Fields:
      additionalProperties:
        $ref: '#/components/schemas/FieldValue'
      examples:
      - fingers:
          type: integer
          value: 10
        firstname:
          type: text
          value: John
        lastname:
          type: text
          value: Doe
      type: object
    Jwk:
      description: Defines an JSON Web Key (JWK) as defined in [the official spec](https://datatracker.ietf.org/doc/html/draft-ietf-jose-json-web-key).
      properties:
        crv:
          $ref: '#/components/schemas/CryptoKeyCurve'
        e:
          examples:
          - AZyi707eeStpr....
          format: binary
          type: string
        "false":
          examples:
          - AZyi707eeStpr....
          format: binary
          type: string
        kid:
          $ref: '#/components/schemas/Uuid'
        kty:
          $ref: '#/components/schemas/CryptoKeyType'
        "true":
          examples:
          - AZyi707eeStpr....
          format: binary
          type: string
        use:
          $ref: '#/components/schemas/JwkUse'
        x:
          examples:
          - AZyi707eeStpr....
          format: binary
          type: string
        x5c:
          examples:
          - MIICHjCCAdCgAwIBAgIQOWVz3...
          format: binary
          type: string
        x5t:
          examples:
          - AZyi707eeStpr....
          format: binary
          type: string
        x5t#S256:
          examples:
          - AZyi707eeStpr....
          format: binary
          type: string
      required:
      - kid
      - kty
      - use
      type: object
    JwkUse:
      enum:
      - sig
      - enc
      type: string
    Jwks:
      description: Defines a store of JWKs as defined in [the official spec](https://openid.net/specs/openid-connect-discovery-1_0-21.html#JWK).
      properties:
        keys:
          items:
            $ref: '#/components/schemas/Jwk'
          type: array
      required:
      - keys
      type: object
    Key:
      examples:
      - foo
      - bar
      - fooBar123
      format: regex
      pattern: '[a-zA-Z][a-zA-Z0-9]*'
      type: string
    Localization:
      properties:
        messages:
          additionalProperties:
            type: string
          examples:
          - bar: Bye!
            foo: Hello!
          type: object
        tag:
          examples:
          - en-US
          - de-DE
          type: string
      requires:
      - tag
      - messages
      type: object
    Oauth2AuthMethod:
      enum:
      - client_secret_basic
      - client_secret_post
      examples:
      - client_secret_post
    Oauth2CodeChallengeMethod:
      enum:
      - none
      - plain
      - S256
      examples:
      - plain
      - S256
    Oauth2GrantType:
      enum:
      - authorization_code
      - refreshToken
    Oauth2ResponseMode:
      enum:
      - query
      - fragment
      - document
      examples:
      - query
      - fragment
      - document
    Oauth2ResponseType:
      enum:
      - code
      - token
    Oauth2Scope:
      examples:
      - profile
      - openid
      - email
      - contacts
      format: regex
      pattern: '[a-zA-Z][a-zA-Z0-9]*(\.[a-zA-Z][a-zA-Z0-9]*)*'
      type: string
    Oauth2SubjectType:
      enum:
      - public
      - pairwise
    OpenIdConnectConfiguration:
      description: Holds the descriptor as part of the OpenID Connect Discovery result.
        See [the official spec](https://openid.net/specs/openid-connect-discovery-1_0.html)
        for more details.
      properties:
        authorization_endpoint:
          examples:
          - https://id.example.com/v1/oauth2/authorize
          format: uri
          type: string
        check_session_iframe:
          examples:
          - https://id.demo.engity.app/v1/oauth2/check-session
          format: uri
          type: string
        claims_supported:
          items:
            $ref: '#/components/schemas/Claim'
          type: array
        code_challenge_methods_supported:
          items:
            $ref: '#/components/schemas/Oauth2CodeChallengeMethod'
          type: array
        device_authorization_endpoint:
          examples:
          - https://id.example.com/v1/oauth2/authorize
          format: uri
          type: string
        id_token_signing_alg_values_supported:
          items:
            $ref: '#/components/schemas/SigningAlgorithm'
          type: array
        issuer:
          examples:
          - https://id.example.com/v1
          format: uri
          type: string
        jwks_uri:
          examples:
          - https://id.demo.engity.app/v1/jwks.json
          format: uri
          type: string
        response_modes_supported:
          items:
            $ref: '#/components/schemas/Oauth2ResponseMode'
          type: array
        response_types_supported:
          items:
            $ref: '#/components/schemas/Oauth2ResponseType'
          type: array
        scopes_supported:
          items:
            $ref: '#/components/schemas/Oauth2Scope'
          type: array
        subject_types_supported:
          items:
            $ref: '#/components/schemas/Oauth2SubjectType'
          type: array
        token_endpoint:
          examples:
          - https://id.example.com/v1/oauth2/token
          format: uri
          type: string
        token_endpoint_auth_methods_supported:
          items:
            $ref: '#/components/schemas/Oauth2AuthMethod'
          type: array
        trigger_verify_contact:
          $ref: '#/components/schemas/Oauth2GrantType'
        userinfo_endpoint:
          examples:
          - https://id.example.com/v1/user
          format: uri
          type: string
      required:
      - issuer
      type: object
    PasswordPresence:
      enum:
      - forbidden
      - optional
      - required
      examples:
      - required
      - forbidden
      type: string
    PasswordRequirement:
      description: Represents a password that should be stored.
      properties:
        type:
          $ref: '#/components/schemas/PasswordType'
        value:
          examples:
          - MIICHjCCAdCgAwIBAgIQOWVz3...
          format: binary
          type: string
      type: object
    PasswordSpec:
      properties:
        presence:
          $ref: '#/components/schemas/PasswordPresence'
        strength:
          $ref: '#/components/schemas/PasswordStrengthSpec'
      required:
      - presence
      type: object
    PasswordStrengthSpec:
      properties:
        maxPossibleScore:
          examples:
          - 4
          maximum: 65535
          minimum: 0
          type: integer
        minRequiredScore:
          examples:
          - 3
          maximum: 65535
          minimum: 0
          type: integer
        type:
          $ref: '#/components/schemas/PasswordStrengthType'
      type: object
    PasswordStrengthType:
      enum:
      - none
      - zxcvbn
      examples:
      - zxcvbn
      type: string
    PasswordType:
      enum:
      - empty
      - plain
      - argon2
      examples:
      - argon2
      type: string
    PhoneNumber:
      enum:
      - "+4930123456789"
      type: string
    Priority:
      default: 0
      maximum: 2.147483647e+09
      minimum: -2.147483648e+09
      type: integer
    SigningAlgorithm:
      enum:
      - HS256
      - HS384
      - HS512
      - PS256
      - PS384
      - PS512
      - RS256
      - RS384
      - RS512
      - ES256
      - ES256K
      - ES384
      - ES512
      - EdDSA
      examples:
      - ES512
      - EdDSA
    StructuredKey:
      examples:
      - foo
      - bar
      - fooBar123
      - foo.bar
      format: regex
      pattern: '[a-zA-Z][a-zA-Z0-9]*(\.[a-zA-Z][a-zA-Z0-9]*)*'
      type: string
    SubPath:
      examples:
      - foo-bar
      format: regex
      pattern: '[a-zA-Z][a-zA-Z0-9]*(-[a-zA-Z][a-zA-Z0-9]*)*'
      type: string
    TeleApprovalVerification:
      discriminator:
        mapping:
          code: '#/components/schemas/TeleApprovalVerificationCode'
        propertyName: type
      oneOf:
      - $ref: '#/components/schemas/TeleApprovalVerificationCode'
      required:
      - type
      type: object
    TeleApprovalVerificationCode:
      properties:
        expected:
          examples:
          - "11"
          type: string
        mocks:
          examples:
          - - "22"
            - "33"
          items:
            type: string
          type: array
        type:
          default: code
          enum:
          - code
          type: string
      required:
      - type
      - expected
      type: object
    TriggerTeleApprovalRequest:
      description: If this object together with its `secret` is defined, a tele approval
        will be initiated, which enables to get informed about the current progress
        state.
      properties:
        secret:
          examples:
          - aSecretBase64String==
          format: binary
          type: string
      type: object
    TriggerTeleApprovalResponse:
      description: If this object is provided and all of its contents are provided
        a tele approval has been started and can be polled with the provided details.
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        verification:
          $ref: '#/components/schemas/TeleApprovalVerification'
      type: object
    User:
      description: Represents a user.
      properties:
        contacts:
          $ref: '#/components/schemas/ContactAssignments'
        createdAt:
          $ref: '#/components/schemas/DateTime'
        fields:
          $ref: '#/components/schemas/Fields'
        id:
          $ref: '#/components/schemas/Uuid'
        lastModifiedAt:
          $ref: '#/components/schemas/DateTime'
        name:
          $ref: '#/components/schemas/StructuredKey'
        passwordType:
          $ref: '#/components/schemas/PasswordType'
        state:
          $ref: '#/components/schemas/UserState'
      required:
      - id
      - createdAt
      - lastModifiedAt
      - state
      type: object
    UserRequirement:
      description: Represents a user that should be created.
      properties:
        contacts:
          $ref: '#/components/schemas/ContactAssignments'
        fields:
          $ref: '#/components/schemas/Fields'
        name:
          $ref: '#/components/schemas/StructuredKey'
        password:
          $ref: '#/components/schemas/PasswordRequirement'
        state:
          $ref: '#/components/schemas/UserState'
      type: object
    UserShort:
      description: Short representation of a user.
      properties:
        createdAt:
          $ref: '#/components/schemas/DateTime'
        id:
          $ref: '#/components/schemas/Uuid'
        lastModifiedAt:
          $ref: '#/components/schemas/DateTime'
        name:
          $ref: '#/components/schemas/StructuredKey'
        state:
          $ref: '#/components/schemas/UserState'
      required:
      - id
      - createdAt
      - lastModifiedAt
      type: object
    UserShorts:
      items:
        $ref: '#/components/schemas/UserShort'
      type: array
    UserState:
      enum:
      - disabled
      - unverified
      - enabled
      - deleted
      examples:
      - enabled
      - unverified
      type: string
    UsernameSpec:
      properties:
        enabled:
          default: false
          examples:
          - true
          type: boolean
      type: object
    Users:
      items:
        $ref: '#/components/schemas/User'
      type: array
    Uuid:
      description: An [Universally Unique Identifier](https://en.wikipedia.org/wiki/Universally_unique_identifier)
        either in its normal format or Base58 encoded.
      examples:
      - 865444E169ZKp6RRMPwVPr
      - 550e8400-e29b-11d4-a716-446655440000
      format: regex
      pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}'
      type: string
  securitySchemes:
    client_oidc:
      openIdConnectUrl: https://{host}{subPath}/v1/.well-known/openid-configuration
      type: openIdConnect
    service_key:
      scheme: bearer
      type: http
tags:
- description: User
  name: user
- description: Clients
  name: clients
- description: Services
  name: services
- description: Resources
  name: resources
- description: Contacts
  name: contacts
- description: Fields
  name: fields
- description: OAuth2
  name: oauth2
- description: OpenID Connect
  name: oidc
externalDocs:
  description: Developer Documentation
  url: https://developers.engity.com/
