Access Controls

Retrieving all access controls

get

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

This endpoint requires the following scopes:

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

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

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

Query parameters

pageNumberinteger · min: 1Optional

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

Default: 1

pageSizeinteger · min: 1Optional

Number of items to be retrieved per page.

Default: 60

metadataModifiedAtstringOptional

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

Example: 2022-01-01

roleIdstringOptionalDeprecated

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

Note: This query parameter is deprecated.

Example: 1rl5e52e-6e27-4ac5-9471-2467d3fb7503

resourceIdstringOptionalDeprecated

Search by the id of a given resource.

Note: This query parameter is deprecated.

qstringOptional

Standard query parameter used to search for specific values.

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

Example: id:in(exampleId1,exampleId2)

expandstring · enumOptionalDeprecated

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

Note: This query parameter is deprecated.

Example: role,resourcePossible values:

Header parameters

X-Total-CountbooleanOptional

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

Default: falseExample: true

Accept-LanguagestringOptional

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

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

Responses

200

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

application/json

400

Unsupported language provided.

application/json

401

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

application/json

403

Scope validation failed, details will be provided in response message

application/json

get

/iam/{tenant}/access-controls

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

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

Retrieving an access control

get

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

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

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

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

accessControlIdstringRequired

Unique identifier of an access control.

Example: 084bcaf6-66b8-4ddd-9489-65c5f6449e94

Query parameters

expandstring · enumOptionalDeprecated

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

Note: This query parameter is deprecated.

Example: role,resourcePossible values:

Header parameters

Accept-LanguagestringOptional

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.

application/json

Definition of access control

idstringOptional

Assignment unique identifier generated when the assignment is created.

roleIdstringOptionalDeprecated

Role unique identifier associated with this access control.

resourceIdstringOptionalDeprecated

Resource unique identifier associated with this access control.

domainsstring[]Optional

Domain identifiers associated with this access control.

Example: ["example_domain"]

scopesstring[]Optional

A list of resolved scopes for a particular access control.

restrictionAwarebooleanOptional

Determines whether this access control generates scopes with restriction suffixes when assigned to a group that has restrictions defined. When true, the generated scopes will include restrictions (e.g. order.order_manage--DE) based on the group's restrictions list. When false, scopes are generated without restriction suffixes regardless of the group's restrictions.

restrictedTostring · enumOptional

Restricts the type of group this access control can be assigned to.

CUSTOMER - the access control can be assigned only to groups of CUSTOMER user type.
EMPLOYEE - the access control can be assigned only to groups of EMPLOYEE user type.

If this property is not present, the access control can be assigned to any group regardless of its user type.

Possible values:

predefinedbooleanRead-onlyOptional

Indicated whether this access control is predefined in the system or was created by a user.

vendorAwarebooleanRead-onlyOptional

Indicated whether this access control is associated with vendor scopes.

400

Unsupported language provided.

application/json

401

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

application/json

403

Scope validation failed, details will be provided in response message

application/json

404

Given resources cannot be found.

application/json

get

/iam/{tenant}/access-controls/{accessControlId}

GET /iam/{tenant}/access-controls/{accessControlId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

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

Upserting an access control

put

Creates an access control when it does not exist, or updates it when it already exists for the tenant. If metadata.version is provided, optimistic locking is applied for updates.

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

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

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

accessControlIdstringRequired

Unique identifier of an access control.

Example: 084bcaf6-66b8-4ddd-9489-65c5f6449e94

Header parameters

Content-LanguagestringRequired

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

Example: de

Body

Payload for creating or updating an access control.

scopesstring[] · min: 1Required

Scope codes for this access control. Must not be empty.

domainsstring[]Optional

Domain identifiers for the access control.

Example: ["example_domain"]

restrictedTostring · enumOptional

Restricts the type of group this access control can be assigned to.

CUSTOMER - the access control can be assigned only to groups of CUSTOMER user type.
EMPLOYEE - the access control can be assigned only to groups of EMPLOYEE user type.

If this property is not present, the access control can be assigned to any group regardless of its user type.

Note: This property is immutable. It can only be set when the access control is created and cannot be changed afterwards.

Possible values:

Responses

201

The request was successful. The access control has been created.

application/json

204

The request was successful. The access control has been updated.

400

Unsupported content language provided.

application/json

401

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

application/json

403

Scope validation failed, details will be provided in response message

application/json

put

/iam/{tenant}/access-controls/{accessControlId}

PUT /iam/{tenant}/access-controls/{accessControlId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Language: de
Content-Type: application/json
Accept: */*
Content-Length: 242

{
  "name": {
    "en": "Example name",
    "de": "Beispielname"
  },
  "description": {
    "en": "Example access control description",
    "de": "Beispielbeschreibung"
  },
  "scopes": [
    "custom.scope"
  ],
  "domains": [
    "example_domain"
  ],
  "restrictedTo": "CUSTOMER",
  "metadata": {
    "version": 1
  }
}

{
  "id": "084bcaf6-66b8-4ddd-9489-65c5f6449e94"
}

Deleting an access control

delete

Deletes a specified access control.

Note: Only user-created access controls can be deleted. Predefined access controls cannot be removed.

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

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

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

accessControlIdstringRequired

Unique identifier of an access control.

Example: 084bcaf6-66b8-4ddd-9489-65c5f6449e94

Responses

204

The request was successful. The access control has been deleted.

401

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

application/json

403

Scope validation failed, details will be provided in response message

application/json

delete

/iam/{tenant}/access-controls/{accessControlId}

DELETE /iam/{tenant}/access-controls/{accessControlId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

PreviousIAM NextScopes

Last updated 7 days ago

Was this helpful?