swagger: '2.0' info: title: Identity Management API description: >- The Identity Management API provides a means form managing users, groups and OAuth clients.
The user and group management is based on SCIM (System for Cross-domain Identity Management).

Note: Unless stated otherwise the Identity Management APIs allow each caller only to act within the context of the tenant to which the caller belong's to.
Note2: UIAM stands for User Identity Access Management, since users and providers are separated in system. Therefore this API documentation is related to users generally. version: '3.1.2' x-visibility: external basePath: /api/identitymanagement/v3 tags: - name: uiam user description: API for Managing Users in a Tenant - name: uiam group description: API for Managing Roles/Groups & Roles/Group Memberships of Users in a Tenant
Note: Roles and groups are made available under /Groups.
Reserved displayNames: starting with "mdspiam:subtenant:" paths: /Groups: get: tags: - uiam group operationId: listGroups summary: List all the groups of a tenant. description: List all the groups of a tenant. parameters: - name: filter in: query description: SCIM filter for searching see [here](http://www.simplecloud.info/specs/draft-scim-api-01.html). required: false type: string - name: count in: query description: Number of objects to be returned (defaults to 100) type: number required: false default: 100 - name: startIndex in: query type: number description: >- The starting index of the search results when paginated. Index starts with 1. required: false default: 1 consumes: - application/json produces: - application/json responses: '200': description: OK schema: $ref: '#/definitions/ScimGroupSearchResults' '401': description: Unauthorized '404': description: Not Found security: - im_group_auth: - 'im.g.r' post: tags: - uiam group operationId: createGroup summary: Create group description: Create a group. parameters: - in: body name: group description: Details of group required: true schema: $ref: '#/definitions/ScimGroupPost' consumes: - application/json produces: - application/json responses: '201': description: Created schema: $ref: '#/definitions/ScimGroup' '400': description: Bad request '401': description: Unauthorized '409': description: Conflict security: - im_group_auth: - 'im.g.c' /Groups/{groupId}: get: tags: - uiam group operationId: getGroup summary: Get group description: Get details of a group.
Example path /api/identitymanagement/v3/Groups/68af46d-e9b8-4t04-5a20-7d557f5da8d parameters: - name: groupId in: path description: Id of group required: true type: string consumes: - application/json produces: - application/json responses: '200': description: OK schema: $ref: '#/definitions/ScimGroup' '401': description: Unauthorized '404': description: Not Found security: - im_group_auth: - 'im.g.r' put: tags: - uiam group operationId: updateGroup summary: Update group. description: Update details of a group. If any field is left empty or is is omitted, it will be null.
Example path /api/identitymanagement/v3/Groups/68af46d-e9b8-4t04-5a20-7d557f5da8d parameters: - name: groupId in: path description: Id of group required: true type: string - in: body name: group description: New details required: true schema: $ref: '#/definitions/ScimGroupPost' consumes: - application/json produces: - application/json responses: '200': description: OK schema: $ref: '#/definitions/ScimGroup' '400': description: Bad request '401': description: Unauthorized '404': description: Not Found security: - im_group_auth: - 'im.g.u' delete: tags: - uiam group operationId: deleteGroup summary: >- Delete group description: Delete group and every connection to that group, too.
Example path /api/identitymanagement/v3/Groups/68af46d-e9b8-4t04-5a20-7d557f5da8d parameters: - name: groupId in: path description: Id of the group required: true type: string consumes: - application/json produces: - application/json responses: '200': description: OK schema: $ref: '#/definitions/ScimGroup' '401': description: Unauthorized '404': description: Not Found security: - im_group_auth: - 'im.g.d' /Groups/{groupId}/members: get: tags: - uiam group operationId: listGroupMembers summary: >- List members of a group description: List the members (both users and groups) of a group.
Example path /api/identitymanagement/v3/Groups/68af46d-e9b8-4t04-5a20-7d557f5da8d/members parameters: - name: groupId in: path description: Id of group required: true type: string consumes: - application/json produces: - application/json responses: '200': description: OK schema: $ref: '#/definitions/ScimGroupMemberList' '401': description: Unauthorized '404': description: Not Found security: - im_group_auth: - 'im.g.r' post: tags: - uiam group operationId: addMemberToGroup summary: >- Add member to a group description: Add new member (either user or group) to an existing group.
Example path /api/identitymanagement/v3/Groups/68af46d-e9b8-4t04-5a20-7d557f5da8d/members parameters: - name: groupId in: path description: Id of group required: true type: string - in: body name: member description: Details of the new member required: true schema: $ref: '#/definitions/ScimGroupMember' consumes: - application/json produces: - application/json responses: '201': description: Created schema: $ref: '#/definitions/ScimGroupMember' '400': description: Bad request '401': description: Unauthorized '404': description: Not Found '409': description: Conflict security: - im_group_auth: - 'im.g.u' /Groups/{groupId}/members/{memberId}: delete: tags: - uiam group operationId: removeMemberFromGroup summary: Delete member from a group description: Delete member (either user or group) from a group.
Example path /api/identitymanagement/v3/Groups/68af46d-e9b8-4t04-5a20-7d557f5da8d/members/e74ff46d-8bb8-4d04-b420-7d557fe86a8d parameters: - name: groupId in: path description: Id of user group required: true type: string - name: memberId in: path description: Id of member required: true type: string consumes: - application/json produces: - application/json responses: '200': description: OK schema: $ref: '#/definitions/ScimGroupMember' '401': description: Unauthorized '404': description: Not Found security: - im_group_auth: - 'im.g.u' /Users: get: tags: - uiam user operationId: list summary: List of users of a tenant. description: List of users of a tenant. Please note, in order to request only the list of users (without the information to which group a user belongs) it is recommended to make use of the "attributes" query parameter as follows /Users?attributes=userName,name,meta (this will significantly improve the performance over simply calling /Users). parameters: - name: filter in: query description: SCIM filter for searching see [here](http://www.simplecloud.info/specs/draft-scim-api-01.html). required: false type: string - name: attributes in: query description: Comma separated list of attribute names to be returned, e.g., userName, name, meta. The attributes parameters does not support the parameter "subtenants". required: false type: string - name: sortBy in: query description: Sorting field name, like email or id required: false type: string - name: sortOrder in: query description: Sort order, ascending/descending (defaults to ascending) type: string required: false default: ascending - name: count in: query description: Number of objects to be returned (defaults to 100) type: number required: false default: 100 - name: startIndex in: query type: number description: The starting index of the search results when paginated. Index starts with 1 (defaults to 1). required: false default: 1 - name: subtenant in: query description: Filter for subtenant users type: string required: false consumes: - application/json produces: - application/json responses: '200': description: OK schema: $ref: '#/definitions/ScimUserResponseSearchResults' '401': description: Unauthorized '404': description: Not Found security: - im_user_auth: - 'im.usr.r' post: tags: - uiam user operationId: create summary: >- Create user description: >- Create a new user in a tenant. parameters: - in: body name: user description: Details of user required: true schema: $ref: '#/definitions/ScimUserPost' consumes: - application/json produces: - application/json responses: '201': description: Created schema: $ref: '#/definitions/ScimUserPostResponse' '401': description: Unauthorized '404': description: Not Found '409': description: Conflict security: - im_user_auth: - 'im.usr.c' /Users/{userId}: get: tags: - uiam user operationId: get summary: >- Get user description: >- Get details of a user.
Example path /api/identitymanagement/v3/Users/2f95913-d3d9-4a4a-951a-c21184080cf3 parameters: - name: userId in: path description: Id of user required: true type: string consumes: - application/json produces: - application/json responses: '200': description: OK schema: $ref: '#/definitions/ScimUserResponse' '401': description: Unauthorized '404': description: Not Found security: - im_user_auth: - 'im.usr.r' put: tags: - uiam user operationId: update summary: >- Update user description: >- Update details of user.

Note: Username must not be changed. Email address is required and must be equal to the username.
Example path /api/identitymanagement/v3/Users/2f95913-d3d9-4a4a-951a-c21184080cf3 parameters: - name: userId in: path description: Id of user required: true type: string - in: body name: user description: New details required: true schema: $ref: '#/definitions/ScimUserPut' consumes: - application/json produces: - application/json responses: '200': description: OK schema: $ref: '#/definitions/ScimUserResponse' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found security: - im_user_auth: - 'im.usr.u' delete: tags: - uiam user operationId: delete summary: >- Delete user description: >- Delete user of tenant.
Note that tenant can have user if it purchased at least the simple offering.
Example path /api/identitymanagement/v3/Users/2f95913-d3d9-4a4a-951a-c21184080cf3 parameters: - name: userId in: path description: Id of user required: true type: string consumes: - application/json produces: - application/json responses: '200': description: OK schema: $ref: '#/definitions/ScimUserResponse' '401': description: Unauthorized security: - im_user_auth: - 'im.usr.d' /Users/me: get: tags: - uiam user operationId: getUserRoles summary: Get list of groups starting with the prefix "mdsp:" in which the user is a member. description: Get list of groups starting with the prefix "mdsp:" in which the user is a member. consumes: - application/json produces: - application/json responses: '200': description: OK schema: type: array items: $ref: '#/definitions/Group' '401': description: Unauthorized '404': description: Not Found security: - im_user_auth: - 'im.usr.me' definitions: Email: type: object required: - value properties: value: type: string description: The email address. example: johndoe@example.com Group: type: object required: - display properties: display: type: string example: mdsp:core:StandardUser type: type: string enum: - DIRECT - INDIRECT example: DIRECT value: type: string example: 85300c9f-9616-4596-ac1c-1ca837426d7e NameRequest: type: object required: - familyName - givenName properties: familyName: type: string example: Doe givenName: type: string example: John NameResponse: type: object properties: familyName: type: string example: Doe givenName: type: string example: John ScimGroupPost: type: object required: - displayName properties: description: type: string example: Very amazing group for amazing people description: Human readable description of the group, displayed e.g. when approving scopes displayName: type: string example: AmazingGroup description: The identifier specified upon creation of the group, unique within the identity zone members: type: array description: If given members array is empty, all members will be deleted. items: $ref: '#/definitions/ScimGroupMember' ScimGroup: type: object properties: id: type: string example: 68af46d-e9b8-4t04-5a20-7d557f5da8d description: The globally unique group ID description: type: string example: Very amazing group for amazing people description: Human readable description of the group, displayed e.g. when approving scopes displayName: type: string example: AmazingGroup description: The identifier specified upon creation of the group, unique within the identity zone members: type: array items: $ref: '#/definitions/ScimGroupMember' meta: $ref: '#/definitions/ScimMeta' ScimGroupMember: type: object required: - type - value properties: type: type: string enum: - USER - GROUP description: Either "USER" or "GROUP" example: USER value: type: string description: Globally unique identifier of the member, either a user ID or another group ID example: e74ff46d-8bb8-4d04-b420-7d557fe86a8d ScimMeta: type: object properties: created: type: string format: date-time example: "2018-02-08T15:20:43.000Z" lastModified: type: string format: date-time example: "2018-02-08T15:20:43.000Z" version: type: integer format: int32 example: 0 ScimUserPut: type: object required: - userName - name - emails description: 'Name object can be null. Example: "name": {}. Name attributes are fetched from WebKey during authentication.' properties: active: type: boolean description: 'False means a soft delete.' name: $ref: '#/definitions/NameRequest' userName: type: string description: The e-mail address of the user. example: johndoe@example.com emails: type: array items: $ref: '#/definitions/Email' subtenants: type: array items: $ref: '#/definitions/SubtenantId' ScimUserPost: type: object required: - userName properties: active: type: boolean description: 'False means a soft delete.' name: $ref: '#/definitions/NameRequest' userName: type: string description: The e-mail address of the user. example: johndoe@example.com subtenants: type: array items: $ref: '#/definitions/SubtenantId' ScimUserResponse: type: object properties: schemas: type: array items: type: string example: urn:scim:schemas:core:1.0 id: example: 2f95913-d3d9-4a4a-951a-c21184080cf3 type: string userName: type: string description: The e-mail address of the user. example: johndoe@example.com name: $ref: '#/definitions/NameResponse' groups: type: array items: $ref: '#/definitions/Group' emails: type: array items: $ref: '#/definitions/Email' active: type: boolean meta: $ref: '#/definitions/ScimMeta' subtenants: type: array items: $ref: '#/definitions/SubtenantId' ScimUserPostResponse: type: object properties: schemas: type: array items: type: string example: urn:scim:schemas:core:1.0 id: example: 2f95913-d3d9-4a4a-951a-c21184080cf3 type: string userName: type: string description: The e-mail address of the user. example: johndoe@example.com name: $ref: '#/definitions/NameResponse' groups: type: array items: $ref: '#/definitions/Group' example: [] emails: type: array items: $ref: '#/definitions/Email' active: type: boolean meta: $ref: '#/definitions/ScimMeta' subtenants: type: array items: $ref: '#/definitions/SubtenantId' ScimGroupMemberList: type: array items: $ref: '#/definitions/ScimGroupMember' ScimGroupSearchResults: type: object properties: itemsPerPage: type: integer format: int32 example: 100 resources: type: array items: $ref: '#/definitions/ScimGroup' schemas: type: array items: type: string example: "urn:scim:schemas:core:1.0" startIndex: type: integer format: int32 example: 1 totalResults: type: integer format: int32 example: 1 ScimUserResponseSearchResults: type: object properties: itemsPerPage: type: integer format: int32 example: 100 resources: type: array items: $ref: '#/definitions/ScimUserResponse' schemas: type: array items: type: string startIndex: type: integer format: int32 example: 1 totalResults: type: integer format: int32 example: 1 SubtenantId: type: object example: id: octopus required: - id properties: id: type: string example: octopus description: The ID / name of the subtenant. securityDefinitions: im_user_auth: type: oauth2 flow: accessCode description: User controller based scopes authorizationUrl: http://UAA_DOMAIN/oauth/authorize tokenUrl: http://UAA_DOMAIN/oauth/token scopes: im.usr.c: Create user im.usr.r: See details of user; List users im.usr.u: Update details of user im.usr.d: Delete user im.usr.me: See the assigened roles of the user im_group_auth: type: oauth2 flow: accessCode description: Group controller based scopes authorizationUrl: http://UAA_DOMAIN/oauth/authorize tokenUrl: http://UAA_DOMAIN/oauth/token scopes: im.g.c: UserUaa - Create group im.g.r: UserUaa - See details of group; UserUaa - List groups; UserUaa - List members of group im.g.u: UserUaa - Update details of group; UserUaa - Add member to group; UserUaa - Remove member of group im.g.d: UserUaa - Delete group