IAM Service

Download OpenAPI specification:Download

With Identity and Access Management (IAM) you can ensure that only users with the right identity credentials can access specified data, resources, or product areas.


Key Features

  • Provides variable levels of user permissions and access rights in the Emporix platform.
  • Apply values across your whole team using Employee Groups.
  • Create and modify Employee Groups, in name & structure.
  • Easily transfer members from one Employee Group to another.
  • Works seamlessly across both Emporix APIs and the Management Dashboard.
  • Integrates widely used protocols, both LDAP and Microsoft’s Active Directory service are supported.

Key Benefits

  • Simple administration: save time by applying permissions across a whole group in a single click.
  • Fewer notifications: free up your inbox by reducing individual permission requests.
  • Stop data leaks: rest assured that only specific user groups have access to sensitive data.
  • Seamless User Experience: users enjoy a more holistic access experience, across APIs and dashboard.

Access Controls

Retrieving all access controls

Retrieves all access controls available for the tenant. The results can be filtered by using query parameters. You can expand the result by resolving the role and resource references.


Required scopes

  • iam.access_read
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

query Parameters
pageNumber
integer >= 1
Default: 1

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

pageSize
integer >= 1
Default: 60

Number of items to be retrieved per page.

metadataModifiedAt
string

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: metadataModifiedAt=2022-01-01
roleId
string

Search by access controls with the roleId field equal to the specified value.

Example: roleId=1rl5e52e-6e27-4ac5-9471-2467d3fb7503
resourceId
string

Search by the id of a given resource.

expand
string

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

Enum: "role,resource" "resource,role" "role" "resource"
Example: expand=role,resource
header Parameters
X-Total-Count
boolean
Default: false

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

Example: true
Accept-Language
string

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 access controls is returned.

400

Unsupported language provided.

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.

403

Scope validation failed, details will be provided in response message

get/{tenant}/access-controls
Request samples
Response samples
application/json
[
  • {
    },
  • {
    }
]

Retrieving an access control

Retrieves details of a specified access control. You can expand the result by resolving the role and resource references.


Required scopes

  • iam.access_read
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

accessControlId
required
string

Unique identifier of an access control, generated when the access control is created.

Example: 084bcaf6-66b8-4ddd-9489-65c5f6449e94
query Parameters
expand
string

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

Enum: "role,resource" "resource,role" "role" "resource"
Example: expand=role,resource
header Parameters
Accept-Language
string

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. Access control details are returned.

400

Unsupported language provided.

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.

403

Scope validation failed, details will be provided in response message

404

Given resources cannot be found.

get/{tenant}/access-controls/{accessControlId}
Request samples
Response samples
application/json
{
  • "id": "I981dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
  • "roleId": "Z843dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
  • "resourceId": "S843dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
  • "name": {
    },
  • "role": {
    },
  • "resource": {
    },
  • "scopes": [
    ],
  • "metadata": {
    }
}

Group Assignments

Adding a user to a group

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_create
  • iam.assignment_create_own
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

groupId
required
string

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

Request Body schema: application/json
userId
required
string

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

userType
string
Default: "EMPLOYEE"

Assignment type, possible values: CUSTOMER, EMPLOYEE

Enum: "CUSTOMER" "EMPLOYEE"
Responses
201

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

400

Request was syntactically incorrect.

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.

403

Scope validation failed, details will be provided in response message

404

Given resources cannot be found.

post/{tenant}/groups/{groupId}/users
Request samples
application/json
{
  • "userId": "f543dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
  • "userType": "CUSTOMER"
}
Response samples
application/json
{
  • "id": "e243dc9e-a3f6-4573-bb01-a8ae21d2d4ae"
}

Removing all users from a group

Removes all users from a specified group.


Required scopes

  • iam.assignment_delete
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

groupId
required
string

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.

403

Scope validation failed, details will be provided in response message

delete/{tenant}/groups/{groupId}/users
Request samples
Response samples
application/json
{
  • "fault": {
    }
}

Removing a user from a group

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_delete
  • iam.assignment_delete_own
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

groupId
required
string

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

userId
required
string

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.

403

Scope validation failed, details will be provided in response message

delete/{tenant}/groups/{groupId}/users/{userId}
Request samples
Response samples
application/json
{
  • "fault": {
    }
}

Removing a user from all groups

Removes a specified user from all groups.


Required scopes

  • iam.assignment_delete
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

userId
required
string

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.

403

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

delete/{tenant}/users/{userId}/groups
Request samples
Response samples
application/json
{
  • "fault": {
    }
}

Groups

Retrieving all groups

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
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

query Parameters
pageNumber
integer >= 1
Default: 1

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

pageSize
integer >= 1
Default: 60

Number of items to be retrieved per page.

sort
string

List of properties used to sort the results, separated by commas. 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.

name
string

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

description
string

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

metadataModifiedAt
string

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: metadataModifiedAt=2022-01-01
userType
string

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

header Parameters
Accept-Language
string

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-Count
boolean
Default: false

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

Example: true
Responses
200

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

400

Unsupported language provided.

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.

403

Scope validation failed, details will be provided in response message

get/{tenant}/groups
Request samples
Response samples
application/json
[
  • {
    },
  • {
    }
]

Creating a new group

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_create
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

header Parameters
Content-Language
required
string

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

Example: de
Request Body schema: application/json
required
object non-empty

Localized group name in the form of a map of translations.

object or null

Localized group description in the form of a map of translations.

object or null

Custom group attributes that need to be included directly in the mixins object.

accessControls
Array of strings or null

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

userType
string or null
Default: "EMPLOYEE"

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

Enum: "CUSTOMER" "EMPLOYEE"
templates
Array of strings or null

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

object

additional properties for B2B

Responses
201

The request was successful. The group has been created.

400

Unsupported content language provided.

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.

403

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

post/{tenant}/groups
Request samples
application/json
{
  • "name": {
    },
  • "description": {
    },
  • "accessControls": [
    ],
  • "templates": [
    ],
  • "b2b": {
    },
  • "userType": "CUSTOMER"
}
Response samples
application/json
{
  • "id": "e243dc9e-a3f6-4573-bb01-a8ae21d2d4ae"
}

Retrieving a group

Retrieves a specified group's details.


Required scopes

  • iam.group_read
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

groupId
required
string

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

header Parameters
Accept-Language
string

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.

400

Unsupported language provided.

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.

403

Scope validation failed, details will be provided in response message

404

Given resources cannot be found.

get/{tenant}/groups/{groupId}
Request samples
Response samples
application/json
{
  • "id": "Z843dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
  • "name": {
    },
  • "description": {
    },
  • "accessControls": [
    ],
  • "b2b": {
    },
  • "mixins": { },
  • "metadata": {
    }
}

Deleting a group

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_delete scope.

Required scopes

  • iam.group_delete
  • iam.assignment_delete if forceDelete is used Note: The iam.assignment_delete scope is only required if you want to delete a group that has users assigned to it.
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

groupId
required
string

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

query Parameters
forceDelete
boolean
Default: false
  • 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_delete scope.

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

Example: forceDelete=false
Responses
204

The request was successful. The group has been deleted.

400

Bad Request

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.

403

Scope validation failed, details will be provided in response message

delete/{tenant}/groups/{groupId}
Request samples
Response samples
application/json
{
  • "resourceId": "12fa14fas-753vs-naoirfau3123",
  • "code": 404,
  • "status": "Bad Request",
  • "message": "Constraint validation failed",
  • "details": [
    ]
}

Updating a group

Updating a group. Proper metadata version value of the updated document is required to perform the request.


Required scopes

  • iam.group_update
SecurityOAuth2
Request
path Parameters
groupId
required
string

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

tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

header Parameters
Content-Language
required
string

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

Example: de
Request Body schema: application/json
required
object non-empty

Localized group name in the form of a map of translations.

object or null

Localized group description in the form of a map of translations.

object or null

Custom group attributes that need to be included directly in the mixins object.

accessControls
Array of strings or null

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

userType
string or null
Default: "EMPLOYEE"

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

Enum: "CUSTOMER" "EMPLOYEE"
templates
Array of strings or null

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

object

additional properties for B2B

metadata
object

Metadata of the updated group. Its version must match the version of the document in the database.

Responses
204

The request was successful. The group has been updated.

400

Unsupported language provided.

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.

403

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

put/{tenant}/groups/{groupId}
Request samples
application/json
{
  • "name": {
    },
  • "description": {
    },
  • "accessControls": [
    ],
  • "templates": [
    ],
  • "b2b": {
    },
  • "userType": "CUSTOMER",
  • "metadata": {
    }
}
Response samples
application/json
{
  • "code": 400,
  • "status": "Bad Request",
  • "message": "Language header validation failed",
  • "details": [
    ]
}

Retrieving all access controls assigned to a group

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
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

groupId
required
string

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

query Parameters
pageNumber
integer >= 1
Default: 1

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

pageSize
integer >= 1
Default: 60

Number of items to be retrieved per page.

expand
string

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

Enum: "role,resource" "resource,role" "role" "resource"
Example: expand=role,resource
header Parameters
X-Total-Count
boolean
Default: false

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

Example: true
Accept-Language
string

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.

400

Unsupported language provided.

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.

403

Scope validation failed, details will be provided in response message

404

Given resources cannot be found.

get/{tenant}/groups/{groupId}/access-controls
Request samples
Response samples
application/json
[
  • {
    },
  • {
    }
]

Retrieving users assigned to a group

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
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

groupId
required
string

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

query Parameters
pageNumber
integer >= 1
Default: 1

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

pageSize
integer >= 1
Default: 60

Number of items to be retrieved per page.

header Parameters
X-Total-Count
boolean
Default: false

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

Example: true
Responses
200

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

400

Unsupported language provided.

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.

403

Scope validation failed, details will be provided in response message

404

Given resources cannot be found.

get/{tenant}/groups/{groupId}/users
Request samples
Response samples
application/json
[
  • {
    },
  • {
    }
]

Permissions

Retrieving all permissions

Retrieves all permissions available for the tenant. You can filter the results by using query parameters.


Required scopes

  • iam.permission_read
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

query Parameters
pageNumber
integer >= 1
Default: 1

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

pageSize
integer >= 1
Default: 60

Number of items to be retrieved per page.

sort
string

List of properties used to sort the results, separated by commas. 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.

name
string

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

description
string

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

metadataModifiedAt
string

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: metadataModifiedAt=2022-01-01
header Parameters
Accept-Language
string

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-Count
boolean
Default: false

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

Example: true
Responses
200

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

400

Unsupported language provided.

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.

403

Scope validation failed, details will be provided in response message

get/{tenant}/permissions
Request samples
Response samples
application/json
[
  • {
    }
]

Retrieving a permission

Retrieves details of a specified permission.


Required scopes

  • iam.permission_read
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

permissionId
required
string

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

Example: 084bcaf6-66b8-4ddd-9489-65c5f6449e94
header Parameters
Accept-Language
string

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. Permission details are returned.

400

Unsupported language provided.

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.

403

Scope validation failed, details will be provided in response message

404

Given resources cannot be found.

get/{tenant}/permissions/{permissionId}
Request samples
Response samples
application/json
{
  • "id": "Z843dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
  • "name": {
    },
  • "description": {
    },
  • "applicableResources": [
    ],
  • "code": "read",
  • "metadata": {
    }
}

Resources

Retrieving all resources

Retrieves all resources of a given tenant. You can filter the results by using query parameters.


Required scopes

  • iam.resource_read
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

query Parameters
pageSize
integer >= 1
Default: 60

Number of items to be retrieved per page.

pageNumber
integer >= 1
Default: 1

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

sort
string

List of properties used to sort the results, separated by commas. 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.

name
string

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

description
string

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

metadataModifiedAt
string

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: metadataModifiedAt=2022-01-01
header Parameters
Accept-Language
string

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-Count
boolean
Default: false

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

Example: true
Responses
200

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

400

Request was syntactically incorrect. Details will be provided in the response payload

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.

403

Scope validation failed, details will be provided in response message

get/{tenant}/resources
Request samples
Response samples
application/json
[
  • {
    }
]

Retrieving a resource

Retrieves details of a specified resource.


Required scopes

  • iam.resource_read
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

resourceId
required
string

Unique identifier of a resource.

header Parameters
Accept-Language
string

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. Resource details are returned.

400

Unsupported language provided.

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.

403

Scope validation failed, details will be provided in response message

404

Given resources cannot be found.

get/{tenant}/resources/{resourceId}
Request samples
Response samples
application/json
{
  • "id": "Z843dc9e-a3f6-4573-bb01-a8ae21d2d4af",
  • "name": {
    },
  • "description": {
    },
  • "code": "serviceName.resource",
  • "metadata": {
    }
}

Roles

Retrieving a list of roles

Retrieves all roles available for a specific tenant. You can filter the results by using query parameters.

Each role contains a permissions list, and each permission is combined with the applicablePermissionResourcesfield. This field allows you to whitelist resources that the permission is applicable to. The field can only contain resources specified in the permission document under applicableResources.


Required scopes

  • iam.role_read
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

query Parameters
pageNumber
integer >= 1
Default: 1

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

pageSize
integer >= 1
Default: 60

Number of items to be retrieved per page.

sort
string

List of properties used to sort the results, separated by commas. 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.

name
string

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

description
string

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

metadataModifiedAt
string

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: metadataModifiedAt=2022-01-01
header Parameters
Accept-Language
string

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-Count
boolean
Default: false

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

Example: true
Responses
200

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

400

Unsupported language provided.

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.

403

Scope validation failed, details will be provided in response message

get/{tenant}/roles
Request samples
Response samples
application/json
[
  • {
    }
]

Retrieving a role

Retrieves details of a specified role.


Required scopes

  • iam.role_read
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

roleId
required
string

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

Example: 084bcaf6-66b8-4ddd-9489-65c5f6449e94
header Parameters
Accept-Language
string

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. Role details are returned.

400

Unsupported language provided.

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.

403

Scope validation failed, details will be provided in response message

404

Given resources cannot be found.

get/{tenant}/roles/{roleId}
Request samples
Response samples
application/json
{
  • "id": "Z843dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
  • "name": {
    },
  • "description": {
    },
  • "permissions": [
    ],
  • "metadata": {
    }
}

Access Control Templates

Retrieving all access control templates

Retrieves all access controls templates available for the tenant. A template contains a list of the most popular access controls combined together in order to provide convenient access to the system.


Required scopes

  • iam.template_read
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

query Parameters
pageNumber
integer >= 1
Default: 1

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

pageSize
integer >= 1
Default: 60

Number of items to be retrieved per page.

sort
string

List of properties used to sort the results, separated by commas. 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.

name
string

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

description
string

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

expand
string

Adds expanded access controls with resource and role objects to the response.

Value: "accessControls"
Example: expand=accessControls
header Parameters
Accept-Language
string

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-Count
boolean
Default: false

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

Example: true
Responses
200

The request was successful. A list of role templates is returned.

400

Unsupported language provided.

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.

403

Scope validation failed, details will be provided in response message

get/{tenant}/templates
Request samples
Response samples
application/json
[
  • {
    }
]

Users

Retrieving all access controls assigned to a user

Retrieves all access controls assigned to a specified user. You can expand the result by resolving the role and resource references.


Required scopes

  • iam.access_read
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

userId
required
string

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

query Parameters
pageNumber
integer >= 1
Default: 1

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

pageSize
integer >= 1
Default: 60

Number of items to be retrieved per page.

expand
string

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

Enum: "role,resource" "resource,role" "role" "resource"
Example: expand=role,resource
header Parameters
X-Total-Count
boolean
Default: false

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

Example: true
Accept-Language
string

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 user access controls is returned.

400

Unsupported language provided.

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.

403

Scope validation failed, details will be provided in response message

404

Given resources cannot be found.

get/{tenant}/users/{userId}/access-controls
Request samples
Response samples
application/json
[
  • {
    },
  • {
    }
]

Retrieving user access controls for a resource

Retrieves a specified user's access controls for a specified resource.


Required scopes

  • iam.access_read
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

userId
required
string

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

resourceId
required
string

Unique identifier of a resource.

query Parameters
expand
string

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

Enum: "role,resource" "resource,role" "role" "resource"
Example: expand=role,resource
header Parameters
Accept-Language
string

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 user access controls for the resource is returned.

400

Unsupported language provided.

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.

403

Scope validation failed, details will be provided in response message

404

Given resources cannot be found.

get/{tenant}/users/{userId}/access-controls/{resourceId}
Request samples
Response samples
application/json
[
  • {
    },
  • {
    }
]

Retrieving all groups to which a user is assigned

Retrieves all groups to which a specified user is assigned.


Required scopes

  • iam.group_read
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

userId
required
string

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

query Parameters
pageNumber
integer >= 1
Default: 1

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

pageSize
integer >= 1
Default: 60

Number of items to be retrieved per page.

sort
string

List of properties used to sort the results, separated by commas. 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-Language
string

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-Count
boolean
Default: false

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

Example: true
Responses
200

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

400

Unsupported language provided.

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.

403

Scope validation failed, details will be provided in response message

get/{tenant}/users/{userId}/groups
Request samples
Response samples
application/json
[
  • {
    }
]

Retrieving user group info

Retrieves user specific group.


Required scopes

  • iam.group_read
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

userId
required
string

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

groupId
required
string

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

header Parameters
Accept-Language
string

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. The group is returned.

400

Unsupported language provided.

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.

403

Scope validation failed, details will be provided in response message

404

Given resources cannot be found.

get/{tenant}/users/{userId}/groups/{groupId}
Request samples
Response samples
application/json
{
  • "id": "Z843dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
  • "name": {
    },
  • "description": {
    },
  • "accessControls": [
    ],
  • "userType": "CUSTOMER",
  • "metadata": {
    }
}

Retrieving user permissions for a resource

Retrieves a specified user's permissions for a specific resource. The permissions are calculated based on the user's group assignments and the access control lists of those groups.


Required scopes

  • iam.permission_read
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

userId
required
string

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

resourceId
required
string

Unique identifier of a resource.

header Parameters
Accept-Language
string

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 user permissions for the resource is returned.

400

Unsupported language provided.

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.

403

Scope validation failed, details will be provided in response message

get/{tenant}/users/{userId}/permissions/{resourceId}
Request samples
Response samples
application/json
[
  • {
    }
]

Retrieving scopes of a specific user

Retrieves all scopes granted to a specified user. Those are calculated based on user group assignments. For each particular group all access controls are resolved to scopes based on defined role(s) and resource(s).


Required scopes

  • iam.scope_read
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

userId
required
string

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

Responses
200

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

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.

403

Scope validation failed, details will be provided in response message

get/{tenant}/users/{userId}/scopes
Request samples
Response samples
application/json
{
  • "userId": "Z843dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
  • "scopes": "iam.group_read iam.roles_read tenant=yourtenant"
}

Retrieving all access controls assigned to a requested user

Retrieves all access controls assigned to a requested user. You can expand the result by resolving the role and resource references.

SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

query Parameters
pageNumber
integer >= 1
Default: 1

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

pageSize
integer >= 1
Default: 60

Number of items to be retrieved per page.

expand
string

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

Enum: "role,resource" "resource,role" "role" "resource"
Example: expand=role,resource
header Parameters
X-Total-Count
boolean
Default: false

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

Example: true
Accept-Language
string

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 user access controls is returned.

400

Unsupported language provided.

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.

403

Scope validation failed, details will be provided in response message

404

Given resources cannot be found.

get/{tenant}/users/me/access-controls
Request samples
Response samples
application/json
[
  • {
    },
  • {
    }
]

Retrieving scopes of a requested user

Retrieves all scopes granted to a requested user. Those are calculated based on user group assignments. For each particular group all access controls are resolved to scopes based on defined role(s) and resource(s).

SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

Responses
200

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

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.

403

Scope validation failed, details will be provided in response message

get/{tenant}/users/me/scopes
Request samples
Response samples
application/json
{
  • "userId": "Z843dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
  • "scopes": "iam.group_read iam.roles_read tenant=yourtenant"
}

Management Dashboard Users

Retrieving a list of users

Retrieves all users for the given tenant with the assigned groups. The user type can be specified as EMPLOYEE or CUSTOMER. Currently, only the EMPLOYEE user type is supported.


Required scopes

  • iam.user_read
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

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

query Parameters
pageNumber
string

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

pageSize
string

Number of items to be retrieved per page.

expand
string

Adds expanded groups objects to the response result.

Value: "groups"
Example: expand=groups