Group Assignments | Documentation Portal

Community Support Portal YouTube Start a free trial

Removing all users from a group

delete

Removes all users from a specified group.

Required scopes

iam.assignment_manage

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: The tenant name should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

groupIdstringRequired

Unique identifier of a group, generated when the group is created.

Responses

204

The request was successful. All users have been deleted from the group.

401

Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.

application/json

403

Scope validation failed, details will be provided in response message

application/json

delete

DELETE /iam/{tenant}/groups/{groupId}/users HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Upserting user assignment to a group

put

Creates user's assignment to a specified group. The user gains all access controls (scopes) specified for this group. In case the assignment already exists, nothing happens as the type of assignment cannot be changed.

Required scopes

iam.assignment_manage

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: The tenant name should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

groupIdstringRequired

Unique identifier of a group, generated when the group is created.

userTypestringRequired

User type that may be one of: 'CUSTOMER', 'EMPLOYEE'

userIdstringRequired

User's unique identifier, generated when the user is created.

Responses

201

The request was successful. The user has been added to the group.

application/json

204

The request was successful. The user assignment already exists and has not been changed.

400

Request was syntactically incorrect.

application/json

401

Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.

application/json

403

Scope validation failed, details will be provided in response message

application/json

404

Given resources cannot be found.

application/json

put

PUT /iam/{tenant}/groups/{groupId}/users/{userType}/{userId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "id": "text"
}

Removing a user from a group

delete

Removes a specified user from a specified group.

iam.assignment_delete_own scope allows customer to remove user from a specified group only if the user is assigned to the same company.

Required scopes

iam.assignment_manage
iam.assignment_delete_own

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: The tenant name should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

groupIdstringRequired

Unique identifier of a group, generated when the group is created.

userIdstringRequired

User's unique identifier, generated when the user is created.

Responses

204

The request was successful. The user has been removed from the group.

401

Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.

application/json

403

Scope validation failed, details will be provided in response message

application/json

delete

DELETE /iam/{tenant}/groups/{groupId}/users/{userId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Retrieving all groups to which a user is assigned

get

Retrieves all groups to which a specified user is assigned.

Required scopes

iam.group_read

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: The tenant name should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

userIdstringRequired

User's unique identifier, generated when the user is created.

Query parameters

pageNumberinteger · min: 1Optional

Page number to be retrieved. The number of the first page is 1.

Default: 1

pageSizeinteger · min: 1Optional

Number of items to be retrieved per page.

Default: 60

sortstringOptional

List of properties used to sort the results, separated by colons. The order of properties indicates their priority in sorting.

Possible values:

{fieldName}
{fieldName}:asc
{fieldName}:desc

Note: If you want to sort the results by localized properties, the possible values are as follows:

{fieldName}.{language}
{fieldName}.{language}:asc
{fieldName}.{language}:desc

If the sorting direction is not specified, the fields are sorted in ascending order.

Header parameters

Accept-LanguagestringOptional

List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields. If the value is specified, then it must be present in the tenant configuration.

If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.
If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.

X-Total-CountbooleanOptional

Flag indicating whether the total number of retrieved items should be returned.

Default: falseExample: true

Responses

200

The request was successful. A list of groups is returned.

application/json

400

Unsupported language provided.

application/json

401

Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.

application/json

403

Scope validation failed, details will be provided in response message

application/json

get

GET /iam/{tenant}/users/{userId}/groups HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "id": "Z843dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
    "name": {
      "en": "Example name",
      "de": "Beispielname"
    },
    "description": {
      "en": "Example group description",
      "de": "Beispiel Berechtigungsbeschreibung"
    },
    "accessControls": [
      "f543dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
      "r243dc9e-a3f6-4573-zz01-a8ae21d2d4ae"
    ],
    "userType": "CUSTOMER",
    "metadata": {
      "version": 1,
      "createdAt": "2022-01-04 10:44:51.871Z",
      "modifiedAt": "2022-01-05 12:44:51.456Z"
    }
  }
]

Removing a user from all groups

delete

Removes a specified user from all groups.

Required scopes

iam.assignment_manage

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: The tenant name should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

userIdstringRequired

User's unique identifier, generated when the user is created.

Responses

204

The request was successful. The user has been removed from all groups.

401

Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.

application/json

403

Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.

application/json

delete

DELETE /iam/{tenant}/users/{userId}/groups HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Retrieving users assigned to a group

get

Retrieves users assignments for a specified group.

iam.user_read_own scope allows customer to retrieve only users assignments from a specified group but only from the same company assignment

Required scopes

iam.user_read
iam.user_read_own

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: The tenant name should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

groupIdstringRequired

Unique identifier of a group, generated when the group is created.

Query parameters

pageNumberinteger · min: 1Optional

Page number to be retrieved. The number of the first page is 1.

Default: 1

pageSizeinteger · min: 1Optional

Number of items to be retrieved per page.

Default: 60

Header parameters

X-Total-CountbooleanOptional

Flag indicating whether the total number of retrieved items should be returned.

Default: falseExample: true

Responses

200

The request was successful. A list of user IDs is returned.

application/json

400

Unsupported language provided.

application/json

401

Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.

application/json

403

Scope validation failed, details will be provided in response message

application/json

404

Given resources cannot be found.

application/json

get

GET /iam/{tenant}/groups/{groupId}/users HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "id": "665776bc-d548-4ec8-8e06-c01491311176",
    "groupId": "1gr5e52e-6e27-4ac5-9471-2467d3fb7504",
    "userId": "00u194ip48TiObqQW417",
    "userType": "CUSTOMER"
  },
  {
    "id": "665776bc-d548-4ec8-8e06-c01491311177",
    "groupId": "1gr5e52e-6e27-4ac5-9471-2467d3fb7502",
    "userId": "00u194ip48TiObqQW411",
    "userType": "CUSTOMER"
  }
]

Adding a user to a group

post

Assigns a user to a specified group. The user will gain all access controls (scopes) specified for this group.

iam.assignment_create_own scope allows customer to assign a user to a specified group only if the user is assigned to the same company.

Required scopes

iam.assignment_manage
iam.assignment_create_own

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: The tenant name should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

groupIdstringRequired

Unique identifier of a group, generated when the group is created.

Body

userIdstringRequired

User unique identifier generated when the user is created. Might be customer ID or Management Dashboard user ID.

userTypestring · enumOptional

Assignment type, possible values: CUSTOMER, EMPLOYEE

Default: EMPLOYEEExample: CUSTOMERPossible values:

Responses

201

The request was successful. The user has been added to the group.

application/json

400

Request was syntactically incorrect.

application/json

401

Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.

application/json

403

Scope validation failed, details will be provided in response message

application/json

404

Given resources cannot be found.

application/json

post

POST /iam/{tenant}/groups/{groupId}/users HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 71

{
  "userId": "f543dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
  "userType": "CUSTOMER"
}

{
  "id": "e243dc9e-a3f6-4573-bb01-a8ae21d2d4ae"
}