Last reviewed: 2021-07-22 |
Note: The term Remove used in in the APIs is exactly the same as the Delete function. Calling any API with the Remove term will result in the associated data being deleted from the database. There is no recovery function for these Remove calls. |
Create a new organization, suborganization or virtual organization.
Collection
Request URL defines the parent of the organization to be created.
POST
Name | Accepted Values | Multivalued | Mandatory | Default | Description |
---|---|---|---|---|---|
virtual | Boolean | false | Defines whether the organization is virtual. | ||
organizationId | String | X | Unique name of the organization to be created. | ||
friendlyName | String | X | Human readable name of the organization. | ||
organizationClass (or organizationType) | String from Configured Set | Organization type defining the initial configuration of the created organization. We support both the old parameter name (organizationClass) and the new parameter name (organizationType). | |||
"custom attribute" | String | X | Organization's custom attribute and a value (multiple values are separated with comma). For example, vatnumber=12345 |
curl --insecure -X POST -u restuser:secret "https://localhost:7443/eidm2/services/orgs/?organizationId=6666666-6&friendlyName=TestOrganization" |
<idlist> <Id>https://HOSTNAME/eidm2/services/org/example1/dep1</Id> </idlist> |
Remove the specified organization.
Entity
Request URL defines the organization to be removed. Response document contains a list of removed entities (organizations, roles, and users).
DELETE
Name | Accepted Values | Multivalued | Mandatory | Default | Description |
---|---|---|---|---|---|
recursive | Boolean | false | Allow deleting organizations with sub-organizations. |
curl --insecure -X DELETE -u restuser:secret "https://localhost:7443/eidm2/services/org/6666666-6?recursive=true" |
<idlist> <Id>https://HOSTNAME/eidm2/services/org/example1/dep1</Id> <Id>https://HOSTNAME/eidm2/services/role/example1/OrganizationMainUser</Id> <Id>https://HOSTNAME/eidm2/services/role/example1/OrganizationUser</Id> <Id>https://HOSTNAME/eidm2/services/user/example1/abcd-1234</Id> <Id>https://HOSTNAME/eidm2/services/user/example1/efgh-5678</Id> </idlist> |
Update the organization data. Replaces all the defined attributes, empty value removes the attribute, and missing attribute does not change the existing value.
Entity
Request URL defines the organization to be updated.
PUT
Name | Accepted Values | Multivalued | Mandatory | Default | Description |
---|---|---|---|---|---|
friendlyName | String | Human readable name of the organization. | |||
organizationClass (or organizationType) | String from Configured Set | Organization type defining the initial configuration of the created organization. We support both the old parameter name (organizationClass) and the new parameter name (organizationType). | |||
"custom attribute" | String | X | Organization's custom attribute and a value (multiple values are separated with comma). These attributes must have been defined in eidm2.properties (data.organization.fields or ui.admin.organizationinfo.fields.order) For example, organizationid=12345 |
curl --insecure -X PUT -u restuser:secret "https://localhost:7443/eidm2/services/org/6666666-6/?friendlyName=TestOrganizationRENAME" |
<idlist> <Id>https://HOSTNAME/eidm2/services/org/example1/dep1</Id> </idlist> |
Update the user information. By default, does not create a new user if the user does not exist. This may be overridden with parameter create. Replaces all the defined attributes, empty value removes the attribute, and missing attribute does not change the existing value. Setting an empty password disables the password method for the user.
Entity
Request URL defines the user to be updated.
PUT
Name | Accepted Values | Multivalued | Mandatory | Default | Description |
---|---|---|---|---|---|
uid | String | User login name. | |||
String | User email address. | ||||
firstname | String | First name of the user. | |||
surname | String | Surname of the user. | |||
mobile | String | Mobile phone number. | |||
locale | String | Locale | |||
hetu | String | Social Security Number (henkilötunnus) | |||
pwd | String | New password. | |||
otp.state (Deprecated) | String | New OTP state. This parameter is deprecated. OTP related REST services will be provided by OTP Server. | |||
pwd.activated | Boolean | Defines if the password authentication method is actived for the user or not. | |||
sms.activated (Deprecated) | Boolean | Defines if the SMS OTP authentication method is actived for the user or not. This parameter is deprecated. SMS OTP related REST services will be provided by OTP Server. | |||
otp.activated (Deprecated) | Boolean | Defines if the OTP authentication method is actived for the user or not. This parameter is deprecated. OTP related REST services will be provided by OTP Server. | |||
create | Boolean | Allow create | |||
disable | Boolean | Disable User | |||
enable | Boolean | Enable User | |||
roles.remove | Boolean | Remove roles | |||
mandates.remove | Boolean | Remove Mandates | |||
"custom attribute" | String | X | User's custom attribute and a value (multiple values are separated with comma). These attributes must have been defined in eidm2.properties (data.user.fields, ui.selfservice.userinfo.fields.order, ui.admin.userinfo.fields.order or ui.admin.approvalinfo.fields.order) For example, age=45 |
curl --insecure -X PUT -u restuser:secret "https://localhost:7443/eidm2/services/user/6666666-6/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/?mobile=%2B358401234567891" |
<idlist> <Id>https://HOSTNAME/eidm2/services/user/example1/user1</Id> </idlist> |
Assign a role for the user.
Collection
Request URL defines the role to be assigned for a user.
POST
Name | Accepted Values | Multivalued | Mandatory | Default | Description |
---|---|---|---|---|---|
user | Entity Name | X | User who the role is assigned for. |
curl --insecure -X POST -u restuser:secret "https://localhost:7443/eidm2/services/assignments/6666666-6/TestRole/?user=6666666-6/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" |
<idlist/> |
Deassign a role from the user.
Collection
Request URL defines the role to be deassign from a user.
DELETE
Name | Accepted Values | Multivalued | Mandatory | Default | Description |
---|---|---|---|---|---|
user | Entity Name | X | User who the role is deassign from. |
curl --insecure -X DELETE -u restuser:secret "https://localhost:7443/eidm2/services/assignments/6666666-6/TestRole/?user=6666666-6/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" |
<idlist/> |
Create a role.
Entity
Request URL defines the role to be created.
PUT
Name | Accepted Values | Multivalued | Mandatory | Default | Description |
---|---|---|---|---|---|
memberOf | String | The created role will be member of this role |
curl --insecure -X PUT -u restuser:secret "https://localhost:7443/eidm2/services/role/6666666-6/TestRole" |
<idlist> <Id>https://HOSTNAME/eidm2/services/role/testorg/testrole</Id> </idlist> |
Remove a role from an organization or a virtual organization.
Entity
Request URL defines the role to be removed.
DELETE
No request specific request URL parameters.
curl --insecure -X DELETE -u restuser:secret "https://localhost:7443/eidm2/services/role/6666666-6/TestRole" |
<idlist> <Id>https://HOSTNAME/eidm2/services/role/testorg/testrole</Id> </idlist> |
Create a new user. Creates a random unique identifier for the user.
NOTE: Be careful to store users only in normal organizations - not virtual, because the system does not currently validate automatically whether the organization is virtual and this will create an inconsistency situation that must be resolved with direct database operations. |
Entity
Request URL defines the organization under which the user will be created.
POST
Name | Accepted Values | Multivalued | Mandatory | Default | Description |
---|---|---|---|---|---|
uid | String | X (depending on configuration) | User login name. | ||
String | X | User email address. | |||
firstname | String | X | First name of the user. | ||
surname | String | X | Surname of the user. | ||
mobile | String | Mobile phone number. | |||
hetu | String | Social Security Number (henkilötunnus) | |||
pwd | String | Initialize the default password authentication method for the user with the specified password. If missing, the password method is not initialized for the user. | |||
pwd.activated | Boolean | Defines if the password authentication method is actived for the user or not. | |||
sms.activated (Deprecated) | Boolean | false | Defines if the SMS OTP authentication method is actived for the user or not. This parameter is deprecated. SMS OTP related REST services will be provided by OTP Server. | ||
otp.activated (Deprecated) | Boolean | false | Defines if the OTP authentication method is actived for the user or not. This parameter is deprecated. OTP related REST services will be provided by OTP Server. | ||
locale | String | Locale definition. It is used when selecting the right language for email notifications. | |||
"custom attribute" | String | X | User's custom attribute and a value (multiple values are separated with comma). These attributes must have been defined in eidm2.properties (data.user.fields, ui.selfservice.userinfo.fields.order, ui.admin.userinfo.fields.order or ui.admin.approvalinfo.fields.order) For example, age=45 |
curl --insecure -X POST -u restuser:secret "https://localhost:7443/eidm2/services/users/6666666-6?uid=leena&firstname=Leena&surname=Laine&email=leena.laine@example.com&pwd=Password1" |
<idlist> <Id>https://HOSTNAME/eidm2/services/user/example1/user1</Id> </idlist> |
Deletes the specified user.
Entity
Request URL defines the user to be deleted.
DELETE
No request specific request URL parameters.
curl --insecure -X DELETE -u restuser:secret "https://localhost:7443/eidm2/services/user/6666666-6/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" |
<idlist> <Id>https://HOSTNAME/eidm2/services/user/example1/user1</Id> </idlist> |
Initialize repository and/or database. Repository initialization creates required sites and authorization policies in LDAP. Database initialization removes and recreates existing database tables.
Initialization should be called only when first installing the system.
Entity
Request URL is static: https://HOSTNAME/eidm2/services/init/
POST
Name | Accepted Values | Multivalued | Mandatory | Default | Description |
---|---|---|---|---|---|
resetRepository | Boolean | false | Removes all organizations, users, and roles from the repository. | ||
initializeDatabase | Boolean | false | Creates the missing mandatory repository structures and roles. Also, updates the repository to reflect the changed configuration. | ||
synchronizeData | Boolean | false | Try to create those items into SQL database that are missing from it but present in LDAP. | ||
initializeOrganizations | Boolean | false | Create roles to organizations based on organization type definitions. Only creates the missing roles but does not remove anything. | ||
clearUniqueFields | Boolean | false | Clears unique field data from validators. | ||
updateSamlApMetadata | Boolean | false | Write SAML AP metadata generated based on the identity file to SSO authentication method configuration. | ||
refreshRoleHierarchyRules | Boolean | false | Updates roles' memberships with other roles to comply with the current Role Hierarchy Rules. Should be run if Role Hierarchy Rules are changed. |
curl --insecure -X POST -u restuser:secret "https://localhost:7443/eidm2/services/init/?resetRepository=true&initializeDatabase=true" |
<idlist/> |
Update all users in given organization.
Entity
Request URL defines the user to be updated.
PUT
Name | Accepted Values | Multivalued | Mandatory | Default | Description |
---|---|---|---|---|---|
disableUsers | Boolean | Disables all users in organization. | |||
enableUsers | Boolean | Enables all users in organization. | |||
deleteUsers | Boolean | Removes all users in organization. | |||
removeRoles | Boolean | Removes all roles and mandate delegations from all users in organization. | |||
removeMandates | Boolean | Removes mandates these users have assigned to other users, mandate delegations received and direct mandate receivals. |
curl --insecure -X PUT -u restuser:secret "https://localhost:7443/eidm2/services/users/6666666-6/?disableUsers=true" |
<idlist> <Id>https://HOSTNAME/eidm2/services/user/example1/user1</Id> <Id>https://HOSTNAME/eidm2/services/user/example1/user2</Id> <Id>https://HOSTNAME/eidm2/services/user/example1/user3</Id> </idlist> |
List users in the organization.
Collection
Request URL defines the organization which users are to be listed. Organization names are handled case insensitively.
GET
Name | Accepted Values | Multivalued | Mandatory | Default | Description |
---|---|---|---|---|---|
entities | Boolean | false | Return list of entities instead of id list. | ||
recursive | Boolean | false | Include users from the suborganizations. | ||
String | Include only users with matching email address. Wildcard '*' is allowed. | ||||
mobile | String | Include only users with matching mobile phone number. Wildcard '*' is allowed. | |||
maxResults | Integer | No Limit | Limit the maximum number of results. Exceeding the limit results in request error with error code 12. A value of zero means no limit. | ||
assignments | Boolean | false | Include role assignments. Effective only if entities is true. | ||
authInfo | Boolean | false | Include authentication credentials. Used for backup or provisioning. Effective only if entities is true. |
curl --insecure -X GET -u restuser:secret "https://localhost:7443/eidm2/services/users/?recursive=true" |
<idlist> <Id>https://HOSTNAME/eidm2/services/user/example1/user1</Id> <Id>https://HOSTNAME/eidm2/services/user/example1/user2</Id> <Id>https://HOSTNAME/eidm2/services/user/example1/dep1/user3</Id> </idlist> |
<entitylist> <user>...</user> <user>...</user> <user>...</user> </entitylist> |
Query information about the specified user.
Entity
Request URL defines the queried user. Supported queries are:
The query is only based on one key-value pair and the priority is as follows: unique id, ssn, login, email, url.
For example, the following query would only query users with SSN.
If none is defined, defaults to Request URL defines the queried user. Organization and user entity names are handled case sensitively.
GET
Name | Accepted Values | Multivalued | Mandatory | Default | Description |
---|---|---|---|---|---|
assignments | Boolean | true | Retrieve role assignments. | ||
groups | Boolean | true | Retrieve group assignments. | ||
authInfo | Boolean | false | Include authentication credentials. Used for backup or provisioning. |
curl --insecure -X GET -u restuser:secret "https://localhost:7443/eidm2/services/user/6666666-6/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" |
<user> <Id>https://HOSTNAME/eidm2/services/user/example1/user1</Id> <organization>https://HOSTNAME/eidm2/services/org/example1</organization> <organizationFriendlyName>Example Inc.</organizationFriendlyName> <status>Enabled</status> <attributes> <uid>john.doe</uid> <firstname>John</firstname> <surname>Doe</surname> <email>john.doe@example.com</email> <mobile>555-1234</mobile> <hetu>123456-7890</hetu> <cn>John Doe</cn> <organization>example1</organization> <customattribute name="custom1"> <value>Value</Value> <value>Value2</Value> </customattribute> </attributes> <roleassignments> <roleassignment> <role> <Id>https://HOSTNAME/eidm2/services/role/example1/testrole</Id> </Role> </roleassignment> </roleassignments> <groupassignments> <groupassignment> <group> <Id>eIDMUser</Id> </group> </groupassignment> </groupassignments> </user> |
Supported values
List organizations.
Collection
Request URL defines the organization in which the organizations to be listed are. Organization names are handled case insensitively.
GET
Name | Accepted Values | Multivalued | Mandatory | Default | Description |
---|---|---|---|---|---|
entities | Boolean | false | Return list of entities instead of id list. | ||
recursive | Boolean | false | Include organizations from the suborganizations. | ||
internal | Boolean | false | Include CustomerID internal organizations. | ||
roles | Boolean | false | List roles available in the organization. | ||
assignments | Boolean | false | Discover users in roles. Effective only if roles is true. | ||
assignmentEntities | Boolean | false | Return user-elements instead of userid-list. Effective only if assignments is true. | ||
applicationCount | Boolean | false | Show pending user application count for organizations (and possibly it's suborganizations). Effective only if entities is true. | ||
recursiveApplicationCount | Boolean | false | Whether to include applications in suborganizations to the count (see applicationCount above). Effective only if applicationCount is true. | ||
friendlyName | String | Include only organizations with friendly name matching the specified filter. Wildcard '*' is allowed in filter string. | |||
organizationType | String from Configured Set | Include only organizations of the specified organizationType. Wildcards are not allowed. | |||
maxResults | Integer | No Limit | Limit the maximum number of results. Exceeding the limit results in request error with error code 12. A value of zero means no limit. | ||
exportMode | Boolean | false | Include all information required for backups and provisioning. Effective only if entities is true. |
curl --insecure -X GET -u restuser:secret "https://localhost:7443/eidm2/services/orgs/?entities=true" curl --insecure -X GET -u restuser:secret "https://localhost:7443/eidm2/services/orgs/?organizationType=virtual" |
<idlist> <Id>https://HOSTNAME/eidm2/services/org/example1</Id> <Id>https://HOSTNAME/eidm2/services/org/example1/dep1</Id> <Id>https://HOSTNAME/eidm2/services/org/example1/dep2</Id> </idlist> |
<entitylist> <organization>...</organization> <organization>...</organization> <organization>...</organization> </entitylist> |
Query information about the specified organization. Organization names are handled case sensitively.
Entity
Request URL defines the queried organization.
GET
Name | Accepted Values | Multivalued | Mandatory | Default | Description |
---|---|---|---|---|---|
roles | Boolean | false | Resolve roles available in the organization. | ||
assignments | Boolean | false | Discover users in roles. Effective only if roles is true. | ||
assignmentEntities | Boolean | false | Return user-elements instead of userid-list. Effective only if assignments is true. | ||
applicationCount | Boolean | false | Return pending user application count for organization (and possibly it's suborganizations) | ||
recursiveApplicationCount | Boolean | false | Whether to include applications in suborganizations to the count (see applicationCount above) | ||
pendingOrganizations | Boolean | false | Returns data of new suborganizations (count, oldest, newest, url for processing) under the current organization, i.e. organizations where no user has yet been approved. | ||
exportMode | Boolean | false | Include all information required for backups and provisioning. |
curl --insecure -X GET -u restuser:secret "https://localhost:7443/eidm2/services/org/6666666-6/" |
<organization> <Id>https://HOSTNAME/eidm2/services/org/example1</Id> <virtual>false</virtual> <friendlyName>Example Inc.</friendlyName> <organizationType>type1</organizationType> <customattribute name="custom1"> <value>Value</Value> <value>Value2</Value> </customattribute> <roles> <role> <Id>https://HOSTNAME/eidm2/services/org/example1/OrganizationMainUser</Id> </Role> </Roles> <applicationCount>0</applicationCount> <pendingOrganizations> <count>2</count> <newest>11.11.2011</newest> <oldest>10.10.2010</oldest> <url>https://<hostname>/eidm2/wf/admin/organization/approval/example1</url> </pendingOrganizations> </organization> |
<organization> <Id>https://HOSTNAME/eidm2/services/org/virtual1</Id> <virtual>true</virtual> <friendlyName>Example Project</friendlyName> <customattribute name="custom1"> <value>Value</Value> <value>Value2</Value> </customattribute> <roles> <role> <Id>https://HOSTNAME/eidm2/services/role/virtual1/OrganizationMainUser</Id> </Role> <role> <Id>https://HOSTNAME/eidm2/services/role/virtual1/OrganizationUser</Id> </Role> </Roles> </organization> |
Supported values
Query information about the specified role. Organization and role names are handled case sensitively.
Entity
Request URL defines the queried role.
GET
Name | Accepted Values | Multivalued | Mandatory | Default | Description |
assignments | Boolean | false | Discover users in the role. Also hierarchical role membership counts, so user A that is a member of role A that is a member of role B is returned when querying the role B. | ||
assignmentEntities | Boolean | false | Return user-elements instead of userid-list. Effective only if assignments is true. |
curl --insecure -X GET -u restuser:secret "https://localhost:7443/eidm2/services/role/6666666-6/TestRole/?assignments=true" |
<role> <Id>https://HOSTNAME/eidm2/services/role/example1/testrole</Id> <roleassignments> <roleassignment> <userid>https://HOSTNAME/eidm2/services/user/example1/user1</userid> </roleassignment> <roleassignment> <userid>https://HOSTNAME/eidm2/services/user/example1/user2</userid> </roleassignment> </roleassignments> </Role> |