The Unity REST API may be exposed (or disabled) as a regular Unity endpoint. See the main Unity documentation for endpoints configuration details.

All paths must be naturally prefixed with the server’s base URL, endpoint deployment’s path (as configured) and API version (currently there is only one). Example query path can be similar to:

https://unity.example.com/rest-admin/v1/entity/1
All operations which are operating on a single entity allow since version 1.9.4 to use three different types of entity selectors. Entity can be specified as an integer number being the internal database identifier of entity in Unity --- this is the only option available in older versions. Alternatively entity’s persistentId can be used. Finally any other identity can be used to select identity, however then a query parameter identityType must be used to provide the intended identity type.

1. API reference

1.1. Resolve identity

@Path("/resolve/{identityType}/{identityValue}")
@GET

Resolves a provided identity of a given type. The returned information is the same as in case of the /entity operation.

Example output:

{
    "entityInformation": {
        "state": "valid",
        "entityId": 1
    },
    "identities": [
        {
            "value": "a",
            "confirmationInfo": {
                "confirmed": false,
                "confirmationDate": 0,
                "sentRequestAmount": 0
            },
            "comparableValue": "a",
            "creationTs": 1491257134658,
            "updateTs": 1491257134658,
            "typeId": "userName",
            "entityId": 1
        },
        {
            "value": "90bba4c5-adbe-4829-8215-e23960c52c33",
            "realm": "main",
            "confirmationInfo": {
                "confirmed": false,
                "confirmationDate": 0,
                "sentRequestAmount": 0
            },
            "comparableValue": "90bba4c5-adbe-4829-8215-e23960c52c33",
            "creationTs": 1491257533387,
            "updateTs": 1491257533387,
            "typeId": "persistent",
            "entityId": 1
        }
    ],
    "credentialInfo": {
        "credentialRequirementId": "Password requirement",
        "credentialsState": {
            "Password credential": {
                "state": "correct",
                "extraInformation": "{\"lastChange\":1491257134733}"
            }
        }
    }
}

1.2. Get entity information

@Path("/entity/{entityId}")
@QueryParam("identityType")
@GET

Returns information about a given entity, including its status and all identities.

Output is the same a in the resolve identity case.

1.3. Get entity groups

@Path("/entity/{entityId}/groups")
@QueryParam("identityType")
@GET
Returns all groups the entity is member of.

Example output:

["/example/sub","/example","/"]

1.4. Get entity attributes

@Path("/entity/{entityId}/attributes")
@QueryParam("group")
@QueryParam("effective")
@QueryParam("identityType")
@QueryParam("includeSimpleValues")
@GET

Returns attributes of a given entity in a selected group. Values are encoded in syntax type dependent way. The optional effective query parameter (by default true) can be used to control whether only directly defined or effective attributes are queried.

Example output:

[
    {
        "values": [
            "2017-04-03T22:18:34"
        ],
        "creationTs": 1491257914036,
        "updateTs": 1491257914036,
        "direct": true,
        "name": "sys:LastAuthentication",
        "groupPath": "/",
        "valueSyntax": "string"
    },
    {
        "values": [
            "Regular User"
        ],
        "creationTs": 1491257136049,
        "updateTs": 1491257136049,
        "direct": true,
        "name": "sys:AuthorizationRole",
        "groupPath": "/",
        "valueSyntax": "enumeration"
    },
    {
        "values": [
            "{\"value\":\"[email protected]\",\"confirmationData\":{\"confirmed\":true,\"confirmationDate\":1491257136061,\"sentRequestAmount\":0},\"tags\":[]}"
        ],
        "creationTs": 1491257136075,
        "updateTs": 1491257136075,
        "direct": true,
        "name": "email",
        "groupPath": "/",
        "valueSyntax": "verifiableEmail"
    },
    {
        "values": [
            "Example organization",
            "org2",
            "org3"
        ],
        "creationTs": 1491257136052,
        "updateTs": 1491257136052,
        "direct": true,
        "name": "o",
        "groupPath": "/",
        "valueSyntax": "string"
    }
]

The optional includeSimpleValues query parameter (by default false) can be used to add to the output additional property with a attributes' values parsed to simple output.

Example output:

    {
        "values": [
            "{\"image\":\"{\\\"type\\\":\\\"PNG\\\",\\\"value\\\":\\\"iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAIAAAAiOjnJAAAzEklEQVR42u1dB1gVxxa\\\"}\",\"externalId\":\"b4118506-3194-4f59-94a7-56c2d3babf00\"}"
        ],
        "creationTs": 1581616749295,
        "updateTs": 1581616749295,
        "direct": true,
        "name": "publicImage",
        "groupPath": "/",
        "valueSyntax": "publicLinkableImage",
        "simpleValues": [
            "https://localhost:2443/unitygw/content/b4118506-3194-4f59-94a7-56c2d3babf00"
        ]
    }

1.5. Get group contents

@Path("/group/{groupPath}")
@GET

Returns all members and subgroups of a given group.

Example output:

{
    "subGroups": [
        "/A/B"
    ],
    "members": [
        {
            "creationTs": 1491257136044,
            "group": "/A",
            "entityId": 2
        },
        {
            "creationTs": 1491257136613,
            "group": "/A",
            "entityId": 4
        }
    ]
}

1.6. Get group members with attributes

@Path("/group-members/{groupPath}")
@GET

Returns all resolved members of a given group: for each member a complete identity information and attributes in the group are returned.

Example output:

[
    {
        "group": "/",
        "entity": {
            // the same as result to resolve identity operation
        },
        "attributes": [
			// the same syntax as in get entity attributes case
        ]
    },
    // ... subsequent group members
]

1.7. Get multiple groups members with attributes

@Path("/group-members-multi/{rootGroupPath}")
@POST
@Consumes(MediaType.APPLICATION_JSON)

Returns all resolved members in all groups under a given path, also including grand children.

The body of the request must be JSON array with strings. If the array is empty then data for all groups is returned. Otherwise the array may contain a set of group names, all of which must be children of rootGroupPath. Only the data for those groups will be returned.

Output structure:

{
    "entities": [
        {
            // the same as result to resolve identity operation
        },
        ...
    ],
    "members": {
        "/root/grp3": [
            {
                "attributes": [
                    {
						// the same syntax as in get entity attributes case
					},
					...
			    ],
                "entityId": 10	//one of group members, of which attributes are provided in this element
            },
            ...
        ],
        ...
    }
}

1.8. Create group

@Path("/group/{groupPath}")
@POST

Creates a new group. The created group will be empty.

1.9. Delete groups

@Path("/group/{groupPath}")
@QueryParam("recursive")
@DELETE

Removes a given group. The optional recursive query parameter can be used to enforce recursive removal (off by default).

1.10. Get group attribute statements

@Path("/group/{groupPath}/statements")
@GET

Returns a JSON array with all attribute statements of a group. Example output:

[
  {
    "resolution":"skip",
    "condition":"true",
    "extraGroupName":"/",
    "dynamicAttributeExpression":"eattr['name']",
    "dynamicAttributeName":"name"
  }
]

1.11. Update group attribute statements

@Path("/group/{groupPath}/statements")
@PUT
@Consumes(MediaType.APPLICATION_JSON)

Updates given group’s attribute statements. The body should contain statements list, same format as returned by the corresponding GET.

1.12. Create entity

@Path("/entity/identity/{type}/{value}")
@QueryParam("credentialRequirement")
@POST

Creates a new entity, with the given initial identity and credential requirement. The new entity is in valid state. New entity id is returned.

Example output:

{"entityId":3}

1.13. Create identity

@Path("/entity/{entityId}/identity/{type}/{value}")
@QueryParam("identityType")
@POST

Creates a new identity for the given entity. No content is returned. Note that for e-mail identities the regular Unity conventions can be used to control confirmation state and tags - see [email-encoding].

1.14. Remove entity

@Path("/entity/{entityId}")
@QueryParam("identityType")
@DELETE

Removes the given entity. No content is returned.

1.15. Schedule user removal

@Path("/entity/{entityId}/removal-schedule")
@QueryParam("when") @QueryParam("identityType")
@PUT

Sets the entity in the state where it can only login and schedules its removal at given time unless the user logs in before this time. No content is returned. This operation is allowed to be called on self .

1.16. Schedule entity operations

@Path("/entity/{entityId}/admin-schedule")
@QueryParam("when") @QueryParam("operation") @QueryParam("identityType")
@PUT

Schedules an operation to be invoked at a given time on an entity. Must be called by privileged user. Allowed operations are: REMOVE and DISABLE.

1.17. Remove identity

@Path("/entity/identity/{type}/{value}")
@DELETE

Removes the given identity. No content is returned.

1.18. Add to group

@Path("/group/{groupPath}/entity/{entityId}")
@QueryParam("identityType")
@POST

Adds the given entity as a member to a group. Note that group must be URL encoded, the / character should be given as %2F. No content is returned.

1.19. Remove from group

@Path("/group/{groupPath}/entity/{entityId}")
@QueryParam("identityType")
@DELETE

Removes a given entity from a group. Note that group must be URL encoded, the / character should be given as %2F. No content is returned.

1.20. Set attribute

@Path("/entity/{entityId}/attribute")
@QueryParam("identityType")
@PUT
@Consumes(MediaType.APPLICATION_JSON)

Sets (creates or updates) an attribute for the given entity. The body of the PUT request describes the attribute: its name, values and group. Its syntax is the same as returned by the GET attributes operation, however the syntax and direct shall not be used. No content is returned. Example attribute encoded (email with two values):

{
  "values": [
    "{\"value\":\"[email protected]\",\"confirmationData\":{\"confirmed\":true,\"confirmationDate\":1491257136061,\"sentRequestAmount\":0},\"tags\":[]}"
  ],
  "name": "email",
  "groupPath": "/A"
}

1.21. Bulk set attributes

@Path("/entity/{entityId}/attributes")
@QueryParam("identityType")
@PUT
@Consumes(MediaType.APPLICATION_JSON)

Bulk attributes creation or update for a given entity. The body of the PUT request describes the attributes. Its root level element must be JSON array. Elements of the array are attributes expressed in the same way as in the singular set attribute operation.

1.22. Remove attribute

@Path("/entity/{entityId}/attribute/{attributeName}")
@QueryParam("identityType")
@QueryParam("group")
@DELETE

Removes the given attribute of an entity. No content is returned.

1.23. Set credential (admin)

@Path("/entity/{entityId}/credential-adm/{credential}")
@QueryParam("identityType")
@PUT
@Consumes(MediaType.APPLICATION_JSON)

Sets a new credential secret for the given entity. The caller must have administrative privileges. Credential name is given as the path parameter, while the secret is carried in the JSON body. No content is returned. For the password credential the complete value could be (with a selected security question and its answer):

{"password":"newpass","answer":"Some answer","question":1}

1.24. Set credential (user)

@Path("/entity/{entityId}/credential/{credential}")
@QueryParam("identityType")
@PUT
@Consumes(MediaType.APPLICATION_JSON)

Sets a new credential secret for the given entity. The caller is assumed to change his/her own credential. Credential name is given as the path parameter, while the new secret is carried in the JSON body. No content is returned. The body must be a JSON array with one element.

the value of the array must be JSON string, not JSON object.
the additional authentication policy of the site must evaluate to the changed credential (typically with the CURRENT entry). Currently it is possible to change only the credential used for authenticating the client.

For the password credential the complete value could be (with a selected security question and its answer):

[
  "{\"password\":\"newpass\",\"answer\":\"Some answer2\",\"question\":0}"
]

1.25. Set credential status

@Path("/entity/{entityId}/credential/{credential}/status/{status}")
@QueryParam("identityType")
@PUT

Sets a given credential status for the user. Allowed status is either notSet (clears the credential) or outdated (invalidated existing credential, user will need to change it after the next interactive login).

1.26. Set 2nd factor (2FA) opt-in for entity

@Path("/entity/{entityId}/2f-optin/{status}")
@QueryParam("identityType")
@PUT

Sets the status of 2nd factor use opt in for an entity. Status can be true or false.

1.27. Get 2nd factor (2FA) opt-in of entity

@Path("/entity/{entityId}/2f-optin")
@QueryParam("identityType")
@GET

Returns string with the status of 2nd factor use opt-in of a given entity.

1.28. Get attribute types

@Path("/attributeTypes")
@GET

Returns an array with all attribute types. Example:

[
    {
        "flags": 1,
        "maxElements": 5,
        "minElements": 1,
        "selfModificable": false,
        "uniqueValues": true,
        "syntaxState": {
            "allowed": [
                "implicit",
                "client",
                "openidHybrid",
                "authorizationCode"
            ]
        },
        "displayedName": {
            "DefaultValue": "sys:oauth:allowedGrantFlows",
            "Map": {
                "pl": "Dozwolone granty OAuth",
                "en": "OAuth client allowed grants"
            }
        },
        "i18nDescription": {
            "DefaultValue": null,
            "Map": {
                "pl": "Atrybut klienta OAauth...",
                "en": "OAuth Client specific attribute..."
            }
        },
        "metadata": {},
        "name": "sys:oauth:allowedGrantFlows",
        "syntaxId": "enumeration"
    },
...
]

1.29. Create attribute type

@Path("/attributeType")
@POST
@Consumes(MediaType.APPLICATION_JSON)

Creates a new attribute type. The POSTed request body must contain a JSON description of the attribute type, with the same syntax as returned by the GET query on attributeTypes. Only a single element is permitted, i.e. do not pass an JSON array. The flags field should be always set to 0.

1.30. Update attribute type

@Path("/attributeType")
@PUT
@Consumes(MediaType.APPLICATION_JSON)

Updates an existing attribute type. The syntax rules are as for POST, however the name of the updated attribute type must resolve to an existing attribute type.

1.31. Remove attribute type

@Path("/attributeType/{toRemove}")
@QueryParam("withInstances")
@DELETE

Removes a given attribute type. Query parameter withInstances is used to control whether all attributes of the removed type should be removed too (value true) or whether the operation should fail if there are any attributes (value false).

1.32. Trigger identity confirmation message

@Path("/confirmation-trigger/identity/{type}/{value}")
@POST

Triggers sending of confirmation message of identity. Nearly always it is a re-send.

1.33. Trigger attribute confirmation message

@Path("/confirmation-trigger/entity/{entityId}/attribute/{attributeName}")
@QueryParam("group")
@QueryParam("identityType")
@POST

Triggers sending of confirmation message for an attribute. Nearly always it is a re-send.

1.34. Get endpoints

@Path("/endpoints")
@GET

Returns all deployed endpoints. Example response with a single endpoint:

[{
        "endpoint": {
            "name": "/admin",
            "typeId": "WebAdminUI",
            "contextAddress": "/admin",
            "configuration": {
                "displayedName": {
                    "DefaultValue": "UNITY administration interface",
                    "Map": {
                        "pl": "Interfejs administracyjny Unity"
                    }
                },
                "description": "",
                "configuration": "unity.endpoint.web.enableRegistration=true\n...",
                "realm": "admin",
                "authenticationOptions": [
                    {
                        "primaryAuthenticator": "pwdWeb1"
                    },
                    {
                        "primaryAuthenticator": "pwdWeb2",
                        "mandatory2ndAuthenticator": "certWeb"
                    },
                    {
                        "primaryAuthenticator": "certWeb",
                        "mandatory2ndAuthenticator": "pwdWeb2"
                    },
                    {
                        "primaryAuthenticator": "certWeb"
                    },
                    {
                        "primaryAuthenticator": "ldapWeb"
                    },
                    {
                        "primaryAuthenticator": "ldapDNWeb"
                    },
                    {
                        "primaryAuthenticator": "samlWeb"
                    },
                    {
                        "primaryAuthenticator": "oauthWeb"
                    }
                ]
            }
        },
        "realm": {
            "description": null,
            "name": "admin",
            "allowForRememberMeDays": 0,
            "blockAfterUnsuccessfulLogins": 5,
            "blockFor": 8,
            "maxInactivity": 600
        },
        "type": {
            "name": "WebAdminUI",
            "description": "Web administrative user interface",
            "supportedBindings": [
                "web-vaadin7"
            ],
            "paths": {
                "/admin": "Web admin endpoint"
            }
        }
    }]
}]

1.35. Undeploy endpoint

@Path("/endpoint/{id}")
@DELETE

Undeploys a deployed endpoint.

1.36. Deploy endpoint

@Path("/endpoint/{id}")
@QueryParam("typeId")
@QueryParam("address")
@POST
@Consumes(MediaType.APPLICATION_JSON)

Instantiates a new endpoint with a given configuration. Type and context path are specified as query parameters. The overall configuration is given in JSON document sent in the request body. Example:

{
  "displayedName" : {
    "DefaultValue" : "endpointName",
    "Map" : { }
  },
  "description" : "endpoint description",
  "authenticationOptions" : [ {
    "primaryAuthenticator" : "ApassREST"
  } ],
  "configuration" : "here comes endpoint configuration, typically in Java properties format",
  "realm" : "authnRealm"
}

1.37. Update endpoint

@Path("/endpoint/{id}")
@PUT
@Consumes(MediaType.APPLICATION_JSON)

Updates the given endpoint’s configuration. The configuration is provided in request body (see POST method for example). If some of the elements are missing, then existing values remain unchanged.

1.38. Get registration forms

@Path("/registrationForms")
@GET

Returns a JSON array with registration forms defined in the system. The syntax is complex and is not provided here.

1.39. Remove registration form

@Path("/registrationForm/{formId}")
@QueryParam("dropRequests")
@DELETE

Removes registration form with the given id. An optional query parameter dropRequests can be provided with a boolean value, to control whether the form should be removed also if it has pending requests (the requests will be removed with the form).

1.40. Create registration form

@Path("/registrationForm")
@POST
@Consumes(MediaType.APPLICATION_JSON)

Creates a new registration form specified by the JSON object passed as request body. The form description is quite complex. The easiest way is to create a registration form using the AdminUI and then check the resulting JSON (GET on /registrationForms).

1.41. Update registration form

@Path("/registrationForm")
@QueryParam("ignoreRequests")
@PUT
@Consumes(MediaType.APPLICATION_JSON)

Updates an existing registration form. The body of the request should include a JSON description of a form, as during form creation. The only difference is that this method expects existing form id. The optional boolean ignoreRequests query parameter can be used to force form update even if it has attached pending requests. Beware, however, that those requests can easily become invalid.

1.42. Get registration requests

@Path("/registrationRequests")
@GET

Returns an array with all registration requests which are stored in the system.

1.43. Get registration request

@Path("/registrationRequest/{requestId}")
@GET

Returns a registration request by its id.

1.44. Get registration invitations

@Path("/invitations")
@GET

Returns a JSON array with all existing invitations.

1.45. Get invitation

@Path("/invitation/{code}")
@GET

Returns a JSON encoded invitation with the specified code.

1.46. Remove invitation

@Path("invitation/{code}")
@DELETE

Removes an invitation with a specified code.

1.47. Send invitation

@Path("invitation/{code}/send")
@POST

Triggers sending a message with an invitation. The registration form of the invitation must have an invitation template defined, and the invitation must have contact address and channel set.

1.48. Create invitation

@Path("invitation")
@POST
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.TEXT_PLAIN)

Creates a new invitation. Returned string is the unique code of the newly created invitation. Example invitation definition:

{
  "formId" : "exForm",
  "expiration" : 1454703788,
  "contactAddress" : "[email protected]",
  "channelId" : "channelId",
  "identities" : {},
  "groupSelections" : {},
  "attributes" : {}
}

Syntax of prefilled parameters, can be seen in the result of retrieving an AdminUI defined invitation via the REST GET methods.

1.49. Update invitation

@Path("invitation/{code}")
@PUT
@Consumes(MediaType.APPLICATION_JSON)

Updates an existing invitation - preserving its code, but changing metadata and prefilled information. The registration form to which invitation was originally issued can not be modified as well as the original contact address.

Body conforms to the same syntax as when creating a new invitation.

1.50. Identity bulk processing

@Path("bulkProcessing/instant")
@QueryParam("timeout")
@POST
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.TEXT_PLAIN)

Schedules a rule for immediate processing. The optional query param timeout controls whether the method should return immediately after scheduling (no parameter) or after completing (parameter set). In the latter case parameter must specify the maximum wait time in seconds. Returned string is the status of scheduling (not the result of the action). Possible statuses are: sync (rule execution was completed in synchronous mode), async (rule was submitted) or timeout (rule was submitted in the synchronous mode but completion await time has passed).

Example rule definition:

{
  "condition" : "(idsByType contains 'userName') && (idsByType['userName'] contains 'user-to-remove')",
  "actionName" : "removeEntity",
  "params" : [ ]
}

1.51. Trigger identity import

@Path("/import/user/{identity}")
@QueryParam("type")
@POST
@Produces(MediaType.APPLICATION_JSON)

Triggers import of the given identity, optionally providing also intended type, though the type is usually not needed. Unity will trigger configured importers in order, stopping at the first which successfully imports the given user. The result is a very detailed dump of import information, starting from status, with unprocessed imported data and processed data after applying the translation profile.

1.52. Trigger system event

@Path("/triggerEvent/{eventName}")
@POST
@Consumes(MediaType.APPLICATION_JSON)

Triggers event with a given name. Body of the request is passed as argument (context) of the event. This feature is typically used to trigger extension script invocation by Unity server: if a script is configured as a handler for the used event it will be launched. That way server REST API functionality can be manually enhanced.

1.53. Get tokens

@Path("/tokens")
@GET
@QueryParam("type")
@QueryParam("owner")
@QueryParam("ownerType")

Returns an array with JSON encoded tokens. If a caller has administrative privileges then returns all tokens. Otherwise returns tokens only which are owned by the caller. The optional owner, ownerType and type query parameters can be used to filter returned tokens.

1.54. Remove token

@Path("/token/{type}/{value}")
@DELETE

Removes a requested token. No content is returned. If a caller has administrative privileges then any token can be removed, otherwise it is allowed for removing owned tokens only.

1.55. Send user notification

@Path("/userNotification-trigger/entity/{identityValue}/template/{templateId}")
@POST
@QueryParam("identityType")

Triggers sending user notification of the given message template. Request may use additional, variable, query parameters which are used as template parameters. All such parameters should have the custom. prefix (which is mandatory in message template for custom properties).