swagger-api_management.yaml

openapi: 3.0.1
info:
  title: Swagger Cloudtrust Management
  description: 'Mangement API for Cloudtrust'
  version: 1.0.0
servers:
- url: http://localhost:8888/management
tags:
- name: Realms
  description: Realms management
- name: Clients
  description: Clients management
- name: Users
  description: Users management
- name: Roles
  description: Roles management
paths:
  /actions:
    get:
      tags:
      - Actions
      summary: Get the list of all possible actions
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Actions'
  /realms/{realm}:
    get:
      tags:
      - Realms
      summary: Get the top-level representation of the realm It will not include nested information like User and Client representations.
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Realm'
  /realms/{realm}/clients:
    get:
      tags:
      - Clients
      summary: Get clients belonging to the realm.
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      responses:
        200:
          description: Returns a list of clients belonging to the realm.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Client'
  /realms/{realm}/required-actions:
    get:
      tags:
      - Required Actions
      summary: Get required actions available for the realm.
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      responses:
        200:
          description: Returns a list of required actions enabled in the realm.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RequiredAction'
  /realms/{realm}/clients/{clientID}:
    get:
      tags:
      - Clients
      summary: Get representation of the client
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: clientID
        in: path
        description: id of client (not client-id)
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Client'
  /realms/{realm}/users:
    post:
      tags:
      - Users
      summary: >
        Create a new user.
        Username must be unique.
        Role and Groups can be assigned thanks to their ID.
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        201:
          description: successful operation
          headers:
            Location:
              schema:
                type: string
              description: URL of the new resource.
    get:
      tags:
      - Users
      summary: >
        Get users.
        Returns a list of users, filtered according to query parameters.
      parameters:
      - name: realm
        in: path
        description: Name of the realm
        required: true
        schema:
          type: string
      - name: groupIds
        in: query
        description: list of groupId the users may belong to (list comma seperated)
        required: true
        schema:
          type: string
      - name: email
        in: query
        schema:
          type: string
        allowEmptyValue: true
      - name: firstName
        in: query
        schema:
          type: string
        allowEmptyValue: true
      - name: lastName
        in: query
        schema:
          type: string
        allowEmptyValue: true
      - name: username
        in: query
        schema:
          type: string
        allowEmptyValue: true
      - name: search
        in: query
        schema:
          type: string
        allowEmptyValue: true
      - name: first
        in: query
        schema:
          type: number
        allowEmptyValue: true
      - name: max
        in: query
        schema:
          type: number
        allowEmptyValue: true
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: number
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
  /realms/{realm}/users/{userID}:
    get:
      tags:
      - Users
      summary: Get representation of the user
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: userID
        in: path
        description: User id
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    put:
      tags:
      - Users
      summary: Update an existing user.
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: userID
        in: path
        description: User id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        200:
          description: successful operation
    delete:
      tags:
      - Users
      summary: Delete the user
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: userID
        in: path
        description: User id
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation
  /realms/{realm}/users/{userID}/status:
    get:
      tags:
      - Users
      summary: Get the account status for the user (User enabled and has a second factor)
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: userID
        in: path
        description: User id
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserStatus'
  /realms/{realm}/users/{userID}/roles:
    get:
      tags:
      - Users
      summary: Get roles of user
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: userID
        in: path
        description: User id
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Role'
  /realms/{realm}/users/{userID}/groups:
    get:
      tags:
      - Users
      summary: Get groups of user
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: userID
        in: path
        description: User id
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Group'
  /realms/{realm}/users/{userID}/role-mappings/clients/{clientID}:
    get:
      tags:
      - Users
      summary: Get client-level roles for the user and the client
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: userID
        in: path
        description: User id
        required: true
        schema:
          type: string
      - name: clientID
        in: path
        description: Client id
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Role'
    post:
      tags:
      - Users
      summary: Add client-level roles to the user.
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: userID
        in: path
        description: User id
        required: true
        schema:
          type: string
      - name: clientID
        in: path
        description: Client id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Role'
      responses:
        200:
          description: successful operation
  /realms/{realm}/users/{userID}/reset-password:
    put:
      tags:
      - Users
      summary: >
        Set up a new password for the user. The value of the password is optional. 
        If no password is provided (i.e. the body is an empty JSON), a password is generated and returned in the response.
        The generated password is a string that either follows the password policy imposed by the realm or has length 8 and contains letters (upper case, lower case) and numbers.
        The password does not contain the following ambiguous characters - l, i,1, 0, o, O, 5, s, S.
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: userID
        in: path
        description: User id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Password'
      responses:
        200:
          description: successful operation
          content:
            text/plain:
              schema:
                type: string
  /realms/{realm}/users/{userID}/execute-actions-email:
    put:
      tags:
      - Users
      summary: >
        Send a update account email to the user An email contains a link the user can click to perform a set of required actions.
        The redirectUri and clientId parameters are optional.
        If no redirect is given, then there will be no link back to click after actions have completed.
        Redirect uri must be a valid uri for the particular clientId.
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: userID
        in: path
        description: User id
        required: true
        schema:
          type: string
      - name: client_id
        in: query
        schema:
          type: string
        allowEmptyValue: true
      - name: lifespan
        in: query
        description: Number of seconds after which the generated token expires
        schema:
          type: string
        allowEmptyValue: true
      - name: redirect_uri
        in: query
        schema:
          type: string
        allowEmptyValue: true
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        200:
          description: successful operation
  /realms/{realm}/users/{userID}/send-new-enrolment-code:
    post:
      tags:
      - Users
      summary: >
        Send a new enrolment code for a particular userID.
      parameters:
      - name: realm
        in: path
        description: Realm name (not id!)
        required: true
        schema:
          type: string
      - name: userID
        in: path
        description: User id
        required: true
        schema:
          type: string
      responses:
        200:
          description: "Code correctly sent by SMS"
        400:
          description: "Invalid input"
        403:
          description: "No permission to call this operation"
  /realms/{realm}/users/{userID}/send-reminder-email:
    post:
      tags:
      - Users
      summary: Send a reminder email for a particular userID.
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: userID
        in: path
        description: User id
        required: true
        schema:
          type: string
      - name: client_id
        in: query
        schema:
          type: string
        allowEmptyValue: true
      - name: redirect_uri
        in: query
        schema:
          type: string
        allowEmptyValue: true
      - name: lifespan
        in: query
        schema:
          type: string          
        allowEmptyValue: true
      responses:
        200:
          description: Mail successfully sent
        400:
          description: Invalid input
        401:
          description: Not authenticated
        403:
          description: No permission to call this operation  
  /realms/{realm}/users/{userID}/reset-sms-counter:
    put:
      tags:
      - Users
      summary: Reset the smsSent attribute of the user to value 0.
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: userID
        in: path
        description: User id
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation          
  /realms/{realm}/users/{userID}/credentials:
    get:
      tags:
      - Credentials
      summary: Get all credentials for the user
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: userID
        in: path
        description: User id
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Credential'
  /realms/{realm}/users/{userID}/recovery-code:
    post:
      tags:
      - Credentials
      summary: Set a recovery code for the user
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: userID
        in: path
        description: User id
        required: true
        schema:
          type: string
      responses:
        201:
          description: successful operation
          content:
            text/plain:
              schema:
                type: string
        409:
          description: recovery code already set
  /realms/{realm}/users/{userID}/credentials/{credentialID}:
    delete:
      tags:
      - Credentials
      summary: Delete the credentials for the user
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: userID
        in: path
        description: User id
        required: true
        schema:
          type: string
      - name: credentialID
        in: path
        description: Credential id
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation
  /realms/{realm}/roles:
    get:
      tags:
      - Roles
      summary: Get all roles for the realm
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Role'
  /realms/{realm}/roles-by-id/{roleID}:
    get:
      tags:
      - Roles
      summary: Get a specific role
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: roleID
        in: path
        description: id of role
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
  /realms/{realm}/clients/{clientID}/roles:
    get:
      tags:
      - Roles
      summary: Get all clients roles
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: clientID
        in: path
        description: id of client (not client-id)
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Role'
    post:
      tags:
      - Roles
      summary: Create a new role for the realm or client
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: clientID
        in: path
        description: id of client (not client-id)
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Role'
      responses:
        201:
          description: successful operation
          headers:
            Location:
              schema:
                type: string
              description: URL of the new resource.
  /realms/{realm}/groups:
    get:
      tags:
      - Groups
      summary: Get the groups available for the realm
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Group'
    post:
      tags:
      - Groups
      summary: Create a new group into the realm
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Group'
      responses:
        201:
          description: successful operation
          headers:
            Location:
              schema:
                type: string
              description: URL of the new resource.
  /realms/{realm}/groups/{groupID}:
    delete:
      tags:
      - Groups
      summary: Delete the group
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: groupID
        in: path
        description: group id
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation
  /realms/{realm}/groups/{groupID}/authorizations:
    get:
      tags:
      - Groups
      summary: Get the authorizations of the group
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: groupID
        in: path
        description: group id
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                  $ref: '#/components/schemas/Authorizations'
    put:
      tags:
      - Groups
      summary: Update the authorizations of the group
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      - name: groupID
        in: path
        description: group id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Authorizations'    
      responses:
        200:
          description: successful operation
  /realms/{realm}/configuration:
    get:
      tags:
      - Configuration
      summary: Get the current configuration
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Configuration'
    put:
      tags:
      - Configuration
      summary: Update the configuration for the given realm
      parameters:
      - name: realm
        in: path
        description: realm name (not id!)
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Configuration'
      responses:
        200:
          description: successful operation
        400:
          description: invalid information provided  (invalid client identifier or redirect URI not allowed for this client)
components:
  schemas:
    Actions:
      type: object
      properties:
        name:
          type: string
        scope:
          type: string
    Realm:
      type: object
      properties:
        id:
          type: string
        keycloakVersion:
          type: string
        realm:
          type: string
        displayName:
          type: string
        enabled:
          type: boolean
          default: true
    User:
      type: object
      properties:
        id:
          type: string
        username:
          type: string
        email:
          type: string
        enabled:
          type: boolean
          default: true
        emailVerified:
          type: boolean
          default: false
        firstName:
          type: string
        lastName:
          type: string
        phoneNumber:
          type: string
        phoneNumberVerified:
          type: boolean
          default: false
        label:
          type: string
        gender:
          type: string
        birthDate:
          type: string
        createdTimestamp:
          type: integer
          format: int64
        groups:
          type: array
          items:
            type: string
        roles:
          type: array
          items:
            type: string
        locale:
          type: string
          default: "en"
    UserStatus:
      type: object
      properties:
        enabled:
          type: boolean
    Client:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        baseUrl:
          type: string
        clientId:
          type: string
        protocol:
          type: string
        enabled:
          type: boolean
          default: true
    RequiredAction:
      type: object
      properties:
        alias:
          type: string
        name:
          type: string
        defaultAction:
          type: boolean
          default: false
    Role:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        clientRole:
          type: string
        composite:
          type: string
        containerId:
          type: string
    Group:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
    Authorizations:
      type: object
      properties:
        matrix:
          type: object
    Password:
      type: object
      properties:
        value:
          type: string
    Credential:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        algorithm:
          type: string
        createdDate:
          type: integer
        config:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    Configuration:
      type: object
      properties:
        default_client_id:
          type: string
        default_redirect_uri:
          type: string
        api_self_authenticator_deletion_enabled:
          type: boolean
        api_self_password_change_enabled:
          type: boolean
        api_self_mail_editing_enabled:
          type: boolean
        api_self_account_deletion_enabled:
          type: boolean
        show_authenticators_tab:
          type: boolean
        show_password_tab:
          type: boolean
        show_mail_editing:
          type: boolean
        show_account_deletion_button:
          type: boolean
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: http://toto.com/.well-known/openid-configuration
security:
  - openId:
    - todo