IAM Service

Download OpenAPI specification:Download

Emporix: documentation@emporix.com URL: https://emporix.com

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


 
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
id
string
Custom group's identifier. If not provided, it is automatically generated


 
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.


409
Resource with given id already exists


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


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


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


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


 
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 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-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 user specified by id. 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 own scopes granted to the user sending the request. 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
userType
string
The user type of the returned users. Currently only the EMPLOYEE user type is supported and is set as default.


 Value: "EMPLOYEE"  
 Example:  userType=EMPLOYEE
header Parameters
X-Total-Count
boolean
 Default:  false
In order to get information how many entities meet a filter requirements, X-Total-Count header has been introduced. The header is optional and its default value is false. It the header is provided and it is true then total count is returned in the X-Total-Count response header. In both cases (X-Total-Count true, false or not provided), the response body has the same format (array of entities). In other words, the information about total count is returned on demand, depending of an existence of X-Total-Count header in a request. Therefore, the X-Total-Count header is not returned if an API consumer didn't ask for it.


 
Responses 
200
The request was successful a list of users is returned.


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


get/{tenant}/users
Request samples 
Response samples 
[
  • {
    },
  • {
    }
]
Create a new user of `EMPLOYEE` type
Creates a new Management Dashboard user for a given tenant. The user will be able to log in to the Management Dashboard right after they confirm their email and set up a password. If a user with a given email already exists in the system, the assignment will be created and no further steps are needed.




Required scopes


    

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


 
Request Body schema: application/json
User creation sample


firstName
required
string
User first name.


 
lastName
required
string
User last name.


 
preferredSite
required
string
User preferred site


 
preferredCurrency
required
string
User preferred currency


 
preferredLanguage
required
string
User preferred language


 
department
required
string
User department


 
contactEmail
required
string
User contact email


 
groupIds
required
Array of strings
Unique identifier of a group associated with to this user. Required to perform the request.


 
Responses 
201
The request was successful. The user has been created.


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 resource cannot be found.


post/{tenant}/users
Request samples 
application/json
{
  • "lastName": "Doe",
  • "firstName": "John",
  • "preferredSite": "main",
  • "contactEmail": "example@emporix.com",
  • "preferredCurrency": "PLN",
  • "preferredLanguage": "en",
  • "department": "departmentName",
  • "groupIds": [
    ]
}
Response samples 
application/json
{
  • "id": "e243dc9e-a3f6-4573-bb01-a8ae21d2d4at"
}
Retrieving a user of the `EMPLOYEE` type
For a specific tenant, retrieves user by ID along with the groups this user belongs to. 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.


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


 
query Parameters
expand
string
Adds expanded groups objects to the response result.


 Value: "groups"  
 Example:  expand=groups
Responses 
200
The request was successful and user 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 resource cannot be found.


get/{tenant}/users/{userId}
Request samples 
Response samples 
application/json
{
  • "id": "00u4ukqvzlEP31sCk417",
  • "firstName": "John",
  • "lastName": "Doe",
  • "backofficeUserNumber": "00u4ukqvzlEP31sCk417",
  • "preferredSite": "main",
  • "preferredCurrency": "PLN",
  • "preferredLanguage": "en",
  • "department": "departmentName",
  • "validFrom": "2022-08-19T10:41:10Z",
  • "isAccountLocked": true,
  • "contactEmail": "user1@gmail.com",
  • "status": "ACTIVE",
  • "groupIds": [
    ],
  • "groups": [
    ]
}
Updating a user of the `EMPLOYEE` type
Updating a user of the EMPLOYEE type. The user will be deleted from all groups and assigned to a given group list based on the groupIds field.




Required scopes


    

  • iam.user_update
    • 



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.


 
Request Body schema: application/json
User creation sample


firstName
required
string
User first name.


 
lastName
required
string
User last name.


 
preferredSite
required
string
User preferred site


 
preferredCurrency
required
string
User preferred currency


 
preferredLanguage
required
string
User preferred language


 
department
required
string
User department


 
backofficeUserNumber
required
string
User backoffice user number. For new users, it is the same as ID. For existing users, it may be different.


 
groupIds
required
Array of strings
Groups unique identifier attached to this user. Required to perform the request.


 
Responses 
204
The request was successful. The user 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
Scope validation failed, details will be provided in response message


404
Given resource cannot be found.


put/{tenant}/users/{userId}
Request samples 
application/json
{
  • "lastName": "Doe",
  • "firstName": "John",
  • "preferredSite": "main",
  • "preferredCurrency": "PLN",
  • "preferredLanguage": "en",
  • "backofficeUserNumber": "00u4ujmuyhhfJodyS417",
  • "department": "departmentName",
  • "groupIds": [
    ]
}
Response samples 
application/json
{
  • "code": 400,
  • "status": "Bad Request",
  • "message": "Language header validation failed",
  • "details": [
    ]
}
Deleting a user from the Management Dashboard
Removes a specified user from all groups. This operation blocks user access to Management Dashboard, but the Developer Portal account access remains the same.




Required scopes


    

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


 
query Parameters
forceDelete
boolean
 Default:  false
Indicates whether user should be deleted from Developer Portal as well.


 
 Example:  forceDelete=false
Responses 
204
User has been deleted successfully.


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}/users/{userId}
Request samples 
Response samples 
application/json
{
  • "fault": {
    }
}