CommunitySupport PortalYouTubeFree trialSign Up!

Groups

Retrieving all groups

get

Retrieves all groups of the tenant. You can filter the results by using query parameters.

iam.group_read_own scope allows customers to retrieve only groups of CUSTOMER type.

Required scopes

  • iam.group_read

  • iam.group_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]+$
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.

namestringOptional

Search by the name of a given resource. The value will be conformed against all of the specified accepted languages.

qstringOptional

Standard query parameter used to search for specific values.

  • Searching for an item by string property: q=id:31065d5b-b62e, where id is the field name and 31065d5b-b62e is its required value.
  • Searching for an item by localized field property: q=name.en:T-s where name is the name of the field, en is a language code and T-s is a required value of this field. This query works only for localized fields, which are stored in a Map format where key is a language code and value is translation to particular language. + Searching for items by date property. All numer-based property queries are valid also for dates. In that case the date should be placed within double quotes: q=metadata.createdAt:(>="2021-05-18T07:27:27.455Z" AND <"2021-05-20T07:27:27.455Z") + Searching for items with non existing or empty property: q=name.en:null where name.en is a name of fields that has value null. + Searching for items with existing property: q=attributes:exists where attributes is a name of field that has non null value. + Searching for items by multiple specific values: q=id:(5c3325baa9812100098ff48f,5c3325d1a9812100098ff494) where id is name of field and strings within a bracket are it''s required value. + Searching for items by multiple fields: q=id:5c3325baa9812100098ff48f name.en:T-s where id and ''name.en'' are the names of fields. All documents that contain given values of these fields are returned. Multiple fields separated by space can be specified. Multiple values for each field can be also specified in a format presented above. + Searching for items with string fields conforming to a regex: q=name.en:~ABCD12 or q=name.en:(~AB CD) - in case of searching for strings with space, where name is the name of field and ABCD12 or AB CD is it''s querying regex.'
Example: id:in(exampleId1,exampleId2)
descriptionstringOptional

Search by the description of the the given resource, it will be conformed against all of the specified accepted-languages.

metadataModifiedAtstringOptional

Search by given resources that contain the metadata.modifiedAt date field with a date later than the specified value. The format is as follows: ''yyyy-MM-dd''.

Example: 2022-01-01
userTypestringOptional

Search by the group user type. Possible values are: CUSTOMER and EMPLOYEE

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
get
/iam/{tenant}/groups
GET /iam/{tenant}/groups HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "id": "1gr5e52e-6e27-4ac5-9471-2467d3fb7500",
    "name": {
      "en": "Customers",
      "de": "Kunden"
    },
    "description": {
      "en": "Storefront users group",
      "de": "Storefront-Benutzergruppe"
    },
    "accessControls": [
      "2ac869fc-d548-4ec8-8e06-c01491314124",
      "2ac869fc-d548-4ec8-8e06-c01491314143",
      "2ac869fc-d548-4ec8-8e06-c01491314144"
    ],
    "templates": [
      "2ac869fc-d548-4ec8-8e06-c01491314144"
    ],
    "code": "CUSTOMER",
    "userType": "CUSTOMER",
    "b2b": {
      "legalEntityId": "0149b1314144a01491314z128"
    },
    "metadata": {
      "version": 1,
      "createdAt": "2022-07-06T16:05:37.673Z",
      "modifiedAt": "2022-07-06T16:05:37.673Z"
    }
  },
  {
    "id": "1gr5e52e-6e27-4ac5-9471-2467d3fb7501",
    "name": {
      "en": "Backoffice users",
      "de": "Backoffice Nutzer"
    },
    "description": {
      "en": "Backoffice users",
      "de": "Backoffice Nutzer"
    },
    "accessControls": [
      "4ac869fc-d548-4ec8-8e06-c01491314102",
      "4ac869fc-d548-4ec8-8e06-c01491314119"
    ],
    "templates": [
      "2ac869fc-d548-4ec8-8e06-c01491314144"
    ],
    "code": "BO_USER",
    "userType": "EMPLOYEE",
    "b2b": {
      "legalEntityId": "0149b1314144a01491314z128"
    },
    "metadata": {
      "version": 1,
      "createdAt": "2022-07-06T16:05:38.119Z",
      "modifiedAt": "2022-07-06T16:05:38.119Z"
    }
  }
]

Creating a new group

post

Creates a new group. When a group is created, you can assign particular users to it. Based on the group's access controls list, you can grant members specific system access.

Required scopes

  • iam.group_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]+$
Header parameters
Content-LanguagestringRequired

The Content-Language request HTTP header defines language(s) of the payload.

Example: de
Body
idstringOptional

Custom group's identifier. If not provided, it is automatically generated

vendorIdstringRead-onlyOptional

An identifier of a vendor to whom the group belongs. Can only be set during creation and is immutable thereafter. A group with vendorId can only be assigned to users of type EMPLOYEE

accessControlsstring[] | nullableOptional

Access control unique identifiers associated with this group. Required to perform the request.

userTypestring · enum | nullableOptional

The type of the group. Possible values: 'CUSTOMER', 'EMPLOYEE'. Default value 'EMPLOYEE' if not provided

Default: EMPLOYEEExample: CUSTOMERPossible values:
templatesstring[] | nullableOptional

Template unique identifier associated with this group. Required to perform the request.

Responses
201

The request was successful. The group has been created.

application/json
post
/iam/{tenant}/groups
POST /iam/{tenant}/groups HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Language: de
Content-Type: application/json
Accept: */*
Content-Length: 365

{
  "name": {
    "en": "Example group name",
    "de": "Beispielname"
  },
  "description": {
    "en": "Example group description",
    "de": "Beispiel Gruppenbeschreibung"
  },
  "accessControls": [
    "f543dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
    "r243dc9e-a3f6-4573-zz01-a8ae21d2d4ae"
  ],
  "templates": [
    "2ac869fc-d548-4ec8-8e06-c01491314144"
  ],
  "b2b": {
    "legalEntityId": "0149b1314144a01491314z128"
  },
  "userType": "CUSTOMER"
}
{
  "id": "e243dc9e-a3f6-4573-bb01-a8ae21d2d4ae"
}

Retrieving a group

get

Retrieves a specified group's details.

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]+$
groupIdstringRequired

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

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.
Responses
200

The request was successful. Group details are returned.

application/json
get
/iam/{tenant}/groups/{groupId}
GET /iam/{tenant}/groups/{groupId} 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"
  ],
  "b2b": {
    "legalEntityId": "0149b1314144a01491314z128"
  },
  "mixins": {},
  "metadata": {
    "version": 1,
    "createdAt": "2022-01-04 10:44:51.871Z",
    "modifiedAt": "2022-01-05 12:44:51.456Z"
  }
}

Upserting a group

put

Updates a user group, or creates a new one if a group with a specified if doesn't exist yet. If you provide the metadata.version, the optimistic locking is enabled and version is validated.

Required scopes

  • iam.group_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.

Header parameters
Content-LanguagestringRequired

The Content-Language request HTTP header defines language(s) of the payload.

Example: de
Body
accessControlsstring[] | nullableOptional

Access control unique identifiers associated with this group. Required to perform the request.

userTypestring · enum | nullableOptional

The type of the group. Possible values: 'CUSTOMER', 'EMPLOYEE'. Default value 'EMPLOYEE' if not provided

Default: EMPLOYEEExample: CUSTOMERPossible values:
templatesstring[] | nullableOptional

Template unique identifier associated with this group. Required to perform the request.

Responses
201

The request was successful. The group has been created.

application/json
put
/iam/{tenant}/groups/{groupId}
PUT /iam/{tenant}/groups/{groupId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Language: de
Content-Type: application/json
Accept: */*
Content-Length: 390

{
  "name": {
    "en": "Example group name",
    "de": "Beispielname"
  },
  "description": {
    "en": "Example group description",
    "de": "Beispiel Gruppenbeschreibung"
  },
  "accessControls": [
    "f543dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
    "r243dc9e-a3f6-4573-zz01-a8ae21d2d4ae"
  ],
  "templates": [
    "2ac869fc-d548-4ec8-8e06-c01491314144"
  ],
  "b2b": {
    "legalEntityId": "0149b1314144a01491314z128"
  },
  "userType": "CUSTOMER",
  "metadata": {
    "version": 1
  }
}
{
  "id": "e243dc9e-a3f6-4573-bb01-a8ae21d2d4ae"
}

Deleting a group

delete

Deletes a specified group.

Important: If you want to delete a group that has users assigned to it, you need to set the forceDelete query parameter to true. In this case, all user group assignments will be deleted as well. The force flag requires the iam.assignment_manage scope.

Required scopes

  • iam.group_manage

  • iam.assignment_manage if forceDelete is used Note: The iam.assignment_manage scope is only required if you want to delete a group that has users assigned to it.

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
forceDeletebooleanOptional

  • If set to true and the group has users assigned to it, both the group and the group assignments will be deleted.

    Important: To set this parameter to true, you must request an access token with the iam.assignment_manage scope.

  • If set to false or not specified and the group has users assigned to it, the endpoint will respond with the 400 error.

Default: falseExample: false
Responses
204

The request was successful. The group has been deleted.

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

No content

Retrieving all access controls assigned to a group

get

Retrieves all access controls assigned to a specified group. Based on that list all users assigned to this group will receive specific system access. You can expand the result by resolving the role and resource references.

Required scopes

  • iam.access_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]+$
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
expandstring · enumOptional

Adds expanded resource and/or role objects to the response.

Example: role,resourcePossible values:
Header parameters
X-Total-CountbooleanOptional

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

Default: falseExample: true
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.
Responses
200

The request was successful. A list of group access controls is returned.

application/json
get
/iam/{tenant}/groups/{groupId}/access-controls
GET /iam/{tenant}/groups/{groupId}/access-controls HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "id": "I981dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
    "roleId": "Z843dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
    "resourceId": "S843dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
    "name": {
      "en": "Example name",
      "de": "Beispielname"
    },
    "role": {
      "id": "Z843dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
      "name": {
        "en": "Example name",
        "de": "Beispielname"
      },
      "description": {
        "en": "Example role description",
        "de": "Beispiel Berechtigungsbeschreibung"
      },
      "permissions": [
        {
          "id": "F243dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
          "applicablePermissionResources": [
            "Q1233dc9e-a3f6-4573-bb01-a8ae21d2d43g"
          ]
        },
        {
          "id": "F343dc9e-a3f6-4573-bb01-a8ae21d2d4ae"
        }
      ],
      "metadata": {
        "version": 1,
        "createdAt": "2022-01-04 10:44:51.871Z",
        "modifiedAt": "2022-01-05 12:44:51.456Z"
      }
    },
    "resource": {
      "id": "S843dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
      "name": {
        "en": "Example name",
        "de": "Beispielname"
      },
      "description": {
        "en": "Example resource description",
        "de": "Beispiel Domainbeschreibung 2"
      },
      "code": "serviceName.resource",
      "metadata": {
        "version": 1,
        "createdAt": "2022-01-04 10:44:51.871Z",
        "modifiedAt": "2022-01-05 12:44:51.456Z"
      }
    },
    "metadata": {
      "version": 1,
      "createdAt": "2019-08-24T14:15:22Z",
      "modifiedAt": "2019-08-24T14:15:22Z"
    }
  },
  {
    "id": "PO43dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
    "roleId": "Rvsf43dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
    "resourceId": "L343dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
    "name": {
      "en": "Example name 2",
      "de": "Beispielname 2"
    },
    "role": {
      "id": "Rvsf43dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
      "name": {
        "en": "Example name 2",
        "de": "Beispielname 2"
      },
      "description": {
        "en": "Example role description 2",
        "de": "Beispiel Berechtigungsbeschreibung 2"
      },
      "permissions": [
        {
          "id": "M243dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
          "applicablePermissionResources": [
            "N943dc9e-a3f6-4573-bb01-a8ae21d2d43g"
          ]
        },
        {
          "id": "Z243dc9e-a3f6-4573-bb01-a8ae21d2d4ae"
        }
      ],
      "metadata": {
        "version": 1,
        "createdAt": "2022-01-04 10:44:51.871Z",
        "modifiedAt": "2022-01-05 12:44:51.456Z"
      }
    },
    "resource": {
      "id": "L343dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
      "name": {
        "en": "Example name 2",
        "de": "Beispielname 2"
      },
      "description": {
        "en": "Example resource description 2",
        "de": "Beispiel Domainbeschreibung 2"
      },
      "code": "serviceName.resource",
      "metadata": {
        "version": 1,
        "createdAt": "2022-01-04 10:44:51.871Z",
        "modifiedAt": "2022-01-05 12:44:51.456Z"
      }
    },
    "metadata": {
      "version": 1,
      "createdAt": "2019-08-24T14:15:22Z",
      "modifiedAt": "2019-08-24T14:15:22Z"
    }
  }
]

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
get
/iam/{tenant}/groups/{groupId}/users
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"
  }
]
PreviousGroup AssignmentsNextPermissions

Was this helpful?