--- title: Configure identities and realms over REST description: This page shows how to use the REST API to manage identities and realms. component: pingam version: 8.1 page_id: pingam:setup:sec-rest-realm-rest canonical_url: https://docs.pingidentity.com/pingam/8.1/setup/sec-rest-realm-rest.html keywords: ["Setup & Configuration", "REST", "Identities", "Realms"] page_aliases: ["setup-guide:sec-rest-realm-rest.adoc"] section_ids: rest-api-crud-identity: Manage identities rest-api-create-identity: Create an identity rest-api-read-identity: Read an identity rest-api-update-identity: Update an identity rest-api-delete-identity: Delete an identity rest-api-query-identity: List identities rest-api-retrieve-identity-using-session-cookie: Get identities with the session cookie rest-api-change-password: Change passwords rest-api-create-group: Create a group rest-api-add-user-to-group: Add a user to a group rest-api-crud-realm: Manage realms rest-api-parameters-realm: Required realm properties rest-api-create-realm: Create a realm rest-api-list-realm: List realms rest-api-read-realm: Read a realm rest-api-update-realm: Update a realm rest-api-delete-realm: Delete a realm --- # Configure identities and realms over REST This page shows how to use the [REST API](../am-rest/preface.html) to manage identities and realms. Long URLs are wrapped to fit the printed page, and some output is formatted for easier reading. Before making a REST API call to manage an identity or realm, make sure that you have: * Authenticated successfully to AM as a user with sufficient privileges to make the REST API call. * Obtained the session token returned after successful authentication. When making the REST API call, pass the [session token](../am-authentication/rest-using-ssotokens.html) in the HTTP header. | | | | - | --------------------------------------------------------------------------------------------------------------- | | | To make REST requests to a specific realm, see [Specify realms in REST API calls](../am-rest/rest-realms.html). | ## Manage identities This section shows how to create, read, update, delete, and list identities using the REST API. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | AM is not primarily an identity store, nor is it provisioning software. For storing identity data, consider PingDS. For provisioning, consider PingIDM. Both of these products provide REST APIs as well. | AM has the `/json/groups` and `/json/users` JSON-based APIs for managing identities. These APIs follow the common REST pattern for creating, reading, updating, deleting, and querying resources. Examples in this section do not repeat the authentication shown in [Authenticate over REST](../am-authentication/authn-rest.html). For browser-based clients, you can rely on AM cookies rather than construct the header in your application. Managing agent profiles, groups, and users with these APIs requires authentication. The examples shown in this section were performed with the token ID gained after authenticating as an AM administrator, for example `amAdmin`. Although the examples here show user management, you can use `/json/groups` in a similar fashion. See [Manage realms](#rest-api-crud-realm) for examples related to realms. The following sections cover this JSON-based API: * [Create an identity](#rest-api-create-identity) * [Read an identity](#rest-api-read-identity) * [Update an identity](#rest-api-update-identity) * [Delete an identity](#rest-api-delete-identity) * [List identities](#rest-api-query-identity) * [Get identities with the session cookie](#rest-api-retrieve-identity-using-session-cookie) * [Change passwords](#rest-api-change-password) * [Create a group](#rest-api-create-group) * [Add a user to a group](#rest-api-add-user-to-group) ### Create an identity AM lets administrators create a user profile with an HTTP POST of the JSON representation of the profile to `/json/subrealm/users/?_action=create`. To add a user to the Top Level Realm, you do not need to specify the realm. The following example shows an administrator creating a new user. The only required fields are `username` and `userpassword`. If no other name is provided, `_id`,`cn`, `sn`, and `uid` are all set to the value of `username`. Values provided for `uid` are not used. ```bash $ curl \ --request POST \ --header "Accept-API-Version: protocol=2.1,resource=3.0" \ --header "Content-Type: application/json" \ --header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \ --data \ '{ "username": "bjensen", "userpassword": "Ch4ng31t", "mail": "bjensen@example.com" }' \ 'https://am.example.com:8443/am/json/realms/root/users/?_action=create' { "_id": "bjensen", "_rev": "-588258934", "username": "bjensen", "realm": "/", "uid": [ "bjensen" ], "mail": [ "bjensen@example.com" ], "universalid": [ "id=bjensen,ou=user,dc=am,dc=example,dc=com" ], "objectClass": [ "iplanet-am-managed-person", "inetuser", "sunFederationManagerDataStore", "sunFMSAML2NameIdentifier", "inetorgperson", "sunIdentityServerLibertyPPService", "devicePrintProfilesContainer", "iplanet-am-user-service", "iPlanetPreferences", "pushDeviceProfilesContainer", "forgerock-am-dashboard-service", "organizationalperson", "top", "kbaInfoContainer", "person", "sunAMAuthAccountLockout", "oathDeviceProfilesContainer", "iplanet-am-auth-configuration-service" ], "inetUserStatus": [ "Active" ], "dn": [ "uid=bjensen,ou=people,dc=am,dc=example,dc=com" ], "cn": [ "bjensen" ], "sn": [ "bjensen" ], "createTimestamp": [ "20180426120642Z" ] } ``` When `LDAP User Search Attribute` and `Authentication Naming Attribute` are set to different attributes, AM treats `id` and `username` as distinct values. In this case, `_id` is mapped to `LDAP User Search Attribute`, which is autogenerated if not specified in the payload, and `username` is mapped to `Authentication Naming Attribute`. For example, given the same payload as above, if `LDAP User Search Attribute` is set to `cn`, the user data is set using the generated UUID as follows: ```bash { "_id":"f3377274-99e4-44f3-8578-0a09914368fc", "_rev":"-1", "realm":"/", "username":"bjensen", "uid":[ "bjensen" ], "mail":["bjensen@example.com"], "universalid":[ "id=f3377274-99e4-44f3-8578-0a09914368fc,ou=user,dc=am,dc=example,dc=com" ], "objectClass":[ …​ ], "inetUserStatus":[ "Active" ], "dn":[ "cn=f3377274-99e4-44f3-8578-0a09914368fc,ou=people,dc=am,dc=example,dc=com"], "cn":[ "f3377274-99e4-44f3-8578-0a09914368fc"], "sn":[ "bjensen" ], "createTimestamp":[ "20220608100442Z" ] } ``` Alternatively, administrators can create user profiles with specific user IDs by doing an HTTP PUT of the JSON representation of the changes to `/json/users/user-id`, as shown in the following example: ```bash $ curl \ --request PUT \ --header "Accept-API-Version: protocol=2.1,resource=3.0" \ --header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \ --header "Content-Type: application/json" \ --header "If-None-Match: *" \ --data \ '{ "username": "janedoe", "userpassword": "Ch4ng31t", "mail": "janedoe@example.com" }' \ 'https://am.example.com:8443/am/json/realms/root/users/janedoe' { "_id": "janedoe", "_rev": "-1686380958", "username": "janedoe", "realm": "/", "uid": [ "janedoe" ], "mail": [ "janedoe@example.com" ], "universalid": [ "id=janedoe,ou=user,dc=am,dc=example,dc=com" ], "objectClass": [ "iplanet-am-managed-person", "inetuser", "sunFederationManagerDataStore", "sunFMSAML2NameIdentifier", "inetorgperson", "sunIdentityServerLibertyPPService", "devicePrintProfilesContainer", "iplanet-am-user-service", "iPlanetPreferences", "pushDeviceProfilesContainer", "forgerock-am-dashboard-service", "organizationalperson", "top", "kbaInfoContainer", "person", "sunAMAuthAccountLockout", "oathDeviceProfilesContainer", "iplanet-am-auth-configuration-service" ], "dn": [ "uid=janedoe,ou=people,dc=am,dc=example,dc=com" ], "inetUserStatus": [ "Active" ], "cn": [ "janedoe" ], "sn": [ "janedoe" ], "createTimestamp": [ "20180426121152Z" ] } ``` As shown in the examples, AM returns the JSON representation of the profile on successful creation. On failure, AM returns a JSON representation of the error including the [HTTP status code](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html). For example, version 2.0 of the common REST `/json/users` and `/json/groups` endpoints return 403 if the user making the request is not authorized to do so. The same HTTP POST and PUT mechanisms also work for other objects, such as groups: ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header "Accept-API-Version: resource=1.0" \ --header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \ --data '{ "username":"newGroup" }' \ 'https://am.example.com:8443/am/json/realms/root/realms/alpha/groups?_action=create' { "username":"newGroup", "realm":"/alpha", "uniqueMember":[ "uid=bjensen,ou=people,dc=am,dc=example,dc=com" ], "cn":[ "newGroup" ], "dn":[ "cn=newGroup,ou=groups,dc=am,dc=example,dc=com" ], "objectclass":[ "groupofuniquenames", "top" ], "universalid":[ "id=newGroup,ou=group,dc=am,dc=example,dc=com" ] } ``` ```bash $ curl \ --request PUT \ --header "If-None-Match: " \ --header "iPlanetDirectoryPro: AQIC5w…​2NzEz" \ --header "Content-Type: application/json" \ --data '{ "username":"anotherGroup", "uniquemember":["uid=bjensen,ou=people,dc=am,dc=example,dc=com"] }' \ 'https://am.example.com:8443/am/json/realms/root/groups/realms/alpha/anotherGroup' { "username":"anotherGroup", "realm":"/alpha", "uniqueMember":[ "uid=bjensen,ou=people,dc=am,dc=example,dc=com" ], "cn":[ "anotherGroup" ], "dn":[ "cn=anotherGroup,ou=groups,dc=am,dc=example,dc=com" ], "objectclass":[ "groupofuniquenames", "top" ], "universalid":[ "id=anotherGroup,ou=group,dc=am,dc=example,dc=com" ] } ``` ### Read an identity AM lets users and administrators read profiles by requesting an HTTP GET on `/json/subrealm/users/user-id`. This allows users and administrators to verify user data, status, and directory. If users or administrators see missing or incorrect information, they can write down the correct information and add it using [Update an identity](#rest-api-update-identity). To read a profile on the Top Level Realm, you do not need to specify the realm. Users can review the data associated with their own accounts, and administrators can also read other user's profiles. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If an administrator user is reading their own profile, an additional `roles` element, with a value of `ui-admin` is returned in the JSON response. The UI verifies this element to grant or deny access to the AM Console. | The following example shows an administrator accessing user data belonging to `bjensen`: ```bash $ curl \ --header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \ 'https://am.example.com:8443/am/json/realms/root/users/bjensen' { "_id":"bjensen", "_rev":"-320505756", "username":"bjensen", "realm":"/", "uid":[ "bjensen" ], "universalid":[ "id=bjensen,ou=user,dc=am,dc=example,dc=com" ], "objectClass":[ "iplanet-am-managed-person", "inetuser", "sunFederationManagerDataStore", "sunFMSAML2NameIdentifier", "devicePrintProfilesContainer", "inetorgperson", "sunIdentityServerLibertyPPService", "iPlanetPreferences", "pushDeviceProfilesContainer", "iplanet-am-user-service", "forgerock-am-dashboard-service", "organizationalperson", "top", "kbaInfoContainer", "sunAMAuthAccountLockout", "person", "oathDeviceProfilesContainer", "iplanet-am-auth-configuration-service" ], "dn":[ "uid=bjensen,ou=people,dc=am,dc=example,dc=com" ], "inetUserStatus":[ "Active" ], "sn":[ "jensen" ], "cn":[ "babs" ], "createTimestamp":[ "20240105101638Z" ], "modifyTimestamp":[ "20240110102632Z" ] } ``` Use the `_fields` query string parameter to restrict the list of attributes returned. This parameter takes a comma-separated list of JSON object fields to include in the result. Note that the `_fields` argument is case-sensitive. In the following example, the returned value matches the specified argument, `uid`, whereas `UID` would not. ```bash $ curl \ --header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \ 'https://am.example.com:8443/am/json/realms/root/users/bjensen?_fields=username,uid' { "username":"bjensen", "uid":[ "bjensen" ] } ``` As shown in the examples, AM returns the JSON representation of the profile on success. On failure, AM returns a JSON representation of the error including the [HTTP status code](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html). ### Update an identity AM lets users update their own profiles, and lets administrators update other users' profiles. To update an identity do an HTTP PUT of the JSON representation of the changes to `/json/subrealm/users/user-id`. To update a profile on the Top Level Realm, you do not need to specify the realm. The following example shows how users can update their own profiles: ```bash $ curl \ --request PUT \ --header "iPlanetDirectoryPro: AQIC5…​Y3MTAx*" \ --header "Content-Type: application/json" \ --header "Accept-API-Version: protocol=2.1,resource=3.0" \ --header "If-Match: *" \ --data '{ "mail": "bjensen@example.com" }' \ 'https://am.example.com:8443/am/json/realms/root/users/bjensen' { "username":"bjensen", "realm":"/", "uid":[ "bjensen" ], "mail":[ "bjensen@example.com" ], "universalid":[ "id=bjensen,ou=user,dc=am,dc=example,dc=com" ], "objectClass":[ "iplanet-am-managed-person", "inetuser", "sunFederationManagerDataStore", "sunFMSAML2NameIdentifier", "devicePrintProfilesContainer", "inetorgperson", "sunIdentityServerLibertyPPService", "iPlanetPreferences", "pushDeviceProfilesContainer", "iplanet-am-user-service", "forgerock-am-dashboard-service", "organizationalperson", "top", "kbaInfoContainer", "sunAMAuthAccountLockout", "person", "oathDeviceProfilesContainer", "iplanet-am-auth-configuration-service" ], "dn":[ "uid=bjensen,ou=people,dc=am,dc=example,dc=com" ], "inetUserStatus":[ "Active" ], "sn":[ "jensen" ], "cn":[ "babs" ], "createTimestamp":[ "20170105101638Z" ], "modifyTimestamp":[ "20170110105038Z" ], "roles":[ "ui-self-service-user" ] } ``` As shown in the example, AM returns the JSON representation of the profile on success. On failure, AM returns a JSON representation of the error including the [HTTP status code](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html). You can use HTTP PUT to update other objects as well, such as groups: Notice in the following example, which updates `newGroup`, the object class value is not included in the JSON sent to AM: ```bash $ curl \ --request PUT \ --header "iPlanetDirectoryPro: AQIC5…​Y3MTAx*" \ --header "Content-Type: application/json" \ --data '{ "uniquemember":[ "uid=newUser,ou=people,dc=am,dc=example,dc=com", "uid=bjensen,ou=people,dc=am,dc=example,dc=com" ] }' \ 'https://am.example.com:8443/am/json/realms/root/realms/alpha/groups/newGroup' { "name":"newGroup", "realm":"/alpha", "uniqueMember":[ "uid=newUser,ou=people,dc=am,dc=example,dc=com", "uid=bjensen,ou=people,dc=am,dc=example,dc=com" ], "cn":[ "newGroup" ], "dn":[ "cn=newGroup,ou=groups,dc=am,dc=example,dc=com" ], "objectclass":[ "groupofuniquenames", "top" ], "universalid":[ "id=newGroup,ou=group,dc=am,dc=example,dc=com" ] } ``` ### Delete an identity AM lets administrators delete a user profile by making an HTTP DELETE call to `/json/subrealm/users/user-id`. To delete a user from the Top Level Realm, you do not need to specify the realm. The following example removes a user from the top level realm. Only administrators should delete users. The user id is the only field required to delete a user: ```bash $ curl \ --request DELETE \ --header "Accept-API-Version: protocol=2.1,resource=3.0" \ --header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \ 'https://am.example.com:8443/am/json/realms/root/users/bjensen' { "_id": "bjensen", "_rev": "-1870449267", "success": "true" } ``` On success, AM returns a JSON object indicating success. On failure, AM returns a JSON representation of the error including the [HTTP status code](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html). You can use this same logic for other resources such as performing an HTTP DELETE on a group: ```bash $ curl \ --request DELETE \ --header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \ --header "Accept-API-Version: resource=1.0" \ 'https://am.example.com:8443/am/json/realms/root/realms/alpha/groups/newGroup' { "success":"true" } ``` | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Deleting a user doesn't automatically remove any of their authenticated sessions. If you are using server-side sessions, you can remove authenticated sessions by checking for any sessions for the user and then removing them using the AM admin UI's Sessions page. If you're using client-side sessions, you can't remove authenticated sessions. You must wait for the sessions to expire. | ### List identities AM lets administrators list identities by making an HTTP GET call to `/json/subrealm/users/?_queryId=*`. To query the Top Level Realm, you do not need to specify the realm: ```bash $ curl \ --header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \ 'https://am.example.com:8443/am/json/realms/root/users?_queryId=*' { "result":[ { "username":"amAdmin", "realm":"dc=am,dc=example,dc=com", "sunIdentityMSISDNNumber":[ ], "mail":[ ], "sn":[ "amAdmin" ], "givenName":[ "amAdmin" ], "universalid":[ "id=amadmin,ou=user,dc=am,dc=example,dc=com" ], "cn":[ "amAdmin" ], "iplanet-am-user-success-url":[ ], "telephoneNumber":[ ], "roles":[ "ui-global-admin", "ui-realm-admin" ], "iplanet-am-user-failure-url":[ ], "inetuserstatus":[ "Active" ], "postalAddress":[ ], "dn":[ "uid=amAdmin,ou=People,dc=am,dc=example,dc=com" ], "employeeNumber":[ ], "iplanet-am-user-alias-list":[ ] }, { "username":"bjensen", "realm":"dc=am,dc=example,dc=com", "uid":[ "bjensen" ], "createTimestamp":[ "20160108155628Z" ], "inetUserStatus":[ "Active" ], "mail":[ "bjensen@example.com" ], "sn":[ "jensen" ], "cn":[ "babs" ], "objectClass":[ "devicePrintProfilesContainer", "person", "sunIdentityServerLibertyPPService", "sunFederationManagerDataStore", "inetorgperson", "oathDeviceProfilesContainer", "iPlanetPreferences", "iplanet-am-auth-configuration-service", "sunFMSAML2NameIdentifier", "organizationalperson", "inetuser", "kbaInfoContainer", "forgerock-am-dashboard-service", "iplanet-am-managed-person", "iplanet-am-user-service", "sunAMAuthAccountLockout", "top" ], "kbaInfo":[ { "questionId":"2", "answer":{ "$crypto":{ "value":{ "algorithm":"SHA-256", "data":"VXGtsnjJMC…​MQJ/goU5hkfF" }, "type":"salted-hash" } } }, { "questionId":"1", "answer":{ "$crypto":{ "value":{ "algorithm":"SHA-256", "data":"cfYYzi9U…​rVfFl0Tdw0iX" }, "type":"salted-hash" } } } ], "dn":[ "uid=bjensen,ou=people,dc=am,dc=example,dc=com" ], "universalid":[ "id=bjensen,ou=user,dc=am,dc=example,dc=com" ], "modifyTimestamp":[ "20160113010610Z" ] } ], "resultCount":2, "pagedResultsCookie":null, "totalPagedResultsPolicy":"NONE", "totalPagedResults":-1, "remainingPagedResults":-1 } ``` The `users` endpoint also supports the `_queryFilter` parameter to alter the returned results. For more information, see [Query](../am-rest/rest-intro.html#about-crest-query). The `_queryId=*` parameter also works for other types of objects, such as groups: ```bash $ curl \ --header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \ --header "Accept-API-Version: resource=1.0" \ 'https://am.example.com:8443/am/json/realms/root/realms/alpha/groups?_queryId=*' { "result" : [ "newGroup", "anotherGroup" ], "resultCount" : 2, "pagedResultsCookie" : null, "remainingPagedResults" : -1 } ``` As the result lists include all objects, this capability to list identity names is mainly useful in testing. As shown in the examples, AM returns the JSON representation of the resource list if successful. On failure, AM returns a JSON representation of the error including the [HTTP status code](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html). ### Get identities with the session cookie If you only have access to the `iPlanetDirectoryPro` session cookie, you can retrieve the user ID by performing an HTTP POST operation on the `/json/users` endpoint using the `idFromSession` action: ```bash $ curl \ --verbose \ --request POST \ --header "Content-Type: application/json" \ --header "Accept-API-Version: protocol=2.1,resource=3.0" \ --header "iPlanetDirectoryPro: AQIC5wM2LY4Sfcz…​c5ODk4MjYzMzA2MQ..*" \ 'https://am.example.com:8443/am/json/realms/root/users?_action=idFromSession' { "id":"bjensen", "realm":"/", "dn":"id=bjensen,ou=user,dc=am,dc=example,dc=com", "successURL":"/am/console", "fullLoginURL":"/am/XUI/?realm=%2F" } ``` ### Change passwords *Users* other than the top-level administrator can change their own passwords with an HTTP POST to `/json/subrealm/users/username?_action=changePassword` including the new password as the value of `userpassword` in the request data. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Changing the top-level administrator's password requires a more complex procedure. See [Changing the amAdmin Password (UI)](../security/securing-administration.html#amadmin-password-console) for more information. | Users must provide the current password, which is set in the request as the value of the `currentpassword`. If a user has forgotten their password, see [Retrieve forgotten usernames](../user-self-service/uss-forgotten-username.html) instead. The following example shows a successful request to change ``bjensen's password to `M0r3Secur3!``: ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header "Accept-API-Version: protocol=2.1,resource=3.0" \ --header "iPlanetDirectoryPro: AQIC5w…​NTcy*" \ --data '{ "currentpassword":"Ch4ng31t", "userpassword":"M0r3Secur3!" }' \ 'https://am.example.com:8443/am/json/realms/root/users/bjensen?_action=changePassword' {} ``` On success, the response is an empty JSON object {} as shown in the example. On failure, AM returns a JSON representation of the error including the [HTTP status code](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html). See also [HTTP Status Codes](../am-rest/rest-intro.html#about-crest-response-codes) for more information. *Administrators* can change non-administrative users' passwords with an HTTP PUT to `/json/subrealm/users/username` including the new password as the value of `userpassword` in the request data. Unlike users, administrators do not provide users' current passwords when changing passwords. The following example shows a successful request by an administrator to change ``bjensen's password to `M0r3Secur3!``: ```bash $ curl \ --request PUT \ --header "iPlanetDirectoryPro: AQIC5w…​NTcy*" \ --header "Accept-API-Version: protocol=2.1,resource=3.0" \ --header "Content-Type: application/json" \ --data '{ "userpassword":"M0r3Secur3!" }' \ 'https://am.example.com:8443/am/json/realms/root/users/bjensen' { "_id":"bjensen", "_rev":"-1942782480", "username":"bjensen", "realm":"/", "uid":[ "bjensen" ], "mail":[ "bjensen@example.com" ], "universalid":[ "id=bjensen,ou=user,dc=am,dc=example,dc=com" ], "objectClass":[ "iplanet-am-managed-person", "inetuser", "sunFederationManagerDataStore", "sunFMSAML2NameIdentifier", "devicePrintProfilesContainer", "inetorgperson", "sunIdentityServerLibertyPPService", "iPlanetPreferences", "pushDeviceProfilesContainer", "iplanet-am-user-service", "forgerock-am-dashboard-service", "organizationalperson", "top", "kbaInfoContainer", "sunAMAuthAccountLockout", "person", "oathDeviceProfilesContainer", "iplanet-am-auth-configuration-service" ], "dn":[ "uid=bjensen,ou=people,dc=am,dc=example,dc=com" ], "inetUserStatus":[ "Active" ], "sn":[ "jensen" ], "cn":[ "babs" ], "modifyTimestamp":[ "20240110105705Z" ], "createTimestamp":[ "20240105101638Z" ] } ``` As shown in the example, AM returns the JSON representation of the profile on success. On failure, AM returns a JSON representation of the error including the [HTTP status code](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html). Learn more in [HTTP Status Codes](../am-rest/rest-intro.html#about-crest-response-codes). ### Create a group AM lets administrators create a group with an HTTP POST of the JSON representation of the group to the `/json/subrealm/groups?_action=create` endpoint. The following example shows how to create a group called `newGroup` in the top level realm using the REST API after authenticating to AM: ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header "Accept-API-Version: resource=1.0" \ --header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \ --data '{ "username":"newGroup" }' \ 'https://am.example.com:8443/am/json/realms/root/realms/alpha/groups?_action=create' { "username":"newGroup", "realm":"/alpha", "uniqueMember":[ "uid=bjensen,ou=people,dc=am,dc=example,dc=com" ], "cn":[ "newGroup" ], "dn":[ "cn=newGroup,ou=groups,dc=am,dc=example,dc=com" ], "objectclass":[ "groupofuniquenames", "top" ], "universalid":[ "id=newGroup,ou=group,dc=am,dc=example,dc=com" ] } ``` ### Add a user to a group AM lets administrators add a user to an existing group with an HTTP PUT to the JSON representation of the group to the `/json/subrealm/groups/groupName` endpoint. The following example shows how to add users to an existing group by using the REST API. The example assumes that the DS backend is in use. Make sure to use the `uniquemember` attribute to specify the user using the DS server: ```bash $ curl \ --request PUT \ --header "iPlanetDirectoryPro: AQIC5…​Y3MTAx*" \ --header "Content-Type: application/json" \ --data '{ "uniquemember":[ "uid=newUser,ou=people,dc=am,dc=example,dc=com", "uid=bjensen,ou=people,dc=am,dc=example,dc=com" ] }' \ 'https://am.example.com:8443/am/json/realms/root/realms/alpha/groups/newGroup' { "name":"newGroup", "realm":"/alpha", "uniqueMember":[ "uid=newUser,ou=people,dc=am,dc=example,dc=com", "uid=bjensen,ou=people,dc=am,dc=example,dc=com" ], "cn":[ "newGroup" ], "dn":[ "cn=newGroup,ou=groups,dc=am,dc=example,dc=com" ], "objectclass":[ "groupofuniquenames", "top" ], "universalid":[ "id=newGroup,ou=group,dc=am,dc=example,dc=com" ] } ``` | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For Active Directory implementations, use the `member` attribute when adding a user to a group using the REST API:```bash $ curl \ --request PUT \ --header "iPlanetDirectoryPro: AQIC5…​Y3MTAx*" \ --header "Content-Type: application/json" \ --data '{ "member":[ "cn=newUser,cn=users,dc=example,dc=com", "cn=bjensen,cn=users,dc=example,dc=com" ] }' \ 'https://am.example.com:8443/am/json/realms/root/realms/alpha/groups/newGroup' { "username": "newGroup", "realm": "/alpha", "sAMAccountName": ["$FL2000-EP4RN8LPBKUS"], "universalid": ["id=newGroup,ou=group,dc=example,dc=com"], "sAMAccountType": ["268435456"], "member": ["cn=newUser,cn=users,dc=example,dc=com", "cn=bjensen,cn=users,dc=example,dc=com"], "name": ["newGroup"], "objectClass": [ "top", "group" ], "distinguishedName": ["CN=newGroup,CN=Users,dc=example,dc=com"], "dn": ["CN=newGroup,CN=Users,dc=example,dc=com"], "cn": ["newGroup"], "objectCategory": ["CN=Group,CN=Schema,CN=Configuration,dc=example,dc=com"] } ``` | ## Manage realms This section shows how to create, read, update, and delete realms using the `/json/global-config/realms` endpoint. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can use the AM API Explorer for detailed information about this endpoint, and to test it against your deployed AM instance.In the AM admin UI, click the Help icon, and then go to API Explorer > /global-config > /realms. | The following sections cover managing realms with the REST API: * [Required realm properties](#rest-api-parameters-realm) * [Create a realm](#rest-api-create-realm) * [List realms](#rest-api-list-realm) * [Read a realm](#rest-api-read-realm) * [Update a realm](#rest-api-update-realm) * [Delete a realm](#rest-api-delete-realm) ### Required realm properties The following table shows the required properties when managing realms using the REST API: **Realm Properties for JSON-based API** | Realm Property | Purpose | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | The name of the realm. Realm names can't match any of the following: Existing realm names. Existing realm aliases. Names of AM REST endpoints. List of names that can't be used for a new realm by default agents api applications applicationtypes authenticate cache conditiontypes dashboard decisioncombiners docs email global-audit global-config groups health metrics policies push realm-audit realm-config realms records resourcetypes scripts selfservice serverinfo sessions subjectattributes subjecttypes things timetravel token tokens users | | `active` | Whether the realm is to be active, or not.Specify either `true` or `false`. | | `parentPath` | The path of the parent realm. | | `aliases` | An array of any applicable aliases associated with the realm. Be aware that an alias can only be used once. Entering an alias used by another realm will remove the alias from that realm and you will lose configuration. | The following JSON object shows an example realm configuration: ```json { "name": "mySubRealm", "active": true, "parentPath": "/", "aliases": [ "payroll.example.com" ] } ``` ### Create a realm AM lets administrators create a realm by performing an HTTP POST of the JSON representation of the realm to `/json/global-config/realms`. The following example creates a new, active subrealm in the top level realm, named `mySubRealm`: ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \ --header "Accept-API-Version: resource=1.0" \ --data '{ "name": "mySubRealm", "active": true, "parentPath": "/", "aliases": [ "payroll.example.com" ] }' \ https://am.example.com:8443/am/json/global-config/realms { "_id": "L2Fub3RoZXJSZWFsbQ", "_rev": "-1054013208", "parentPath": "/", "active": true, "name": "mySubRealm", "aliases": [ "payroll.example.com" ] } ``` AM returns a 201 HTTP status code and a JSON representation of the realm on success. The value returned in the `_id` field is used in subsequent REST calls relating to the realm. On failure, AM returns a JSON representation of the error including the HTTP status code. For more information, see [HTTP Status Codes](../am-rest/rest-intro.html#about-crest-response-codes). ### List realms To list and query realms, perform an HTTP GET on the `/json/global-config/realms` endpoint, and set the `_queryFilter` query string parameter to `true` as in the following example, which lists all available realms: ```bash $ curl \ --header "iPlanetDirectoryPro: AQIC5…​" \ --header "Accept-API-Version: resource=1.0, protocol=2.1" \ https://am.example.com:8443/am/json/global-config/realms?_queryFilter=true { "result":[ { "_id":"Lw", "_rev":"252584985", "parentPath":null, "active":true, "name":"/", "aliases":[ "am.example.com", "am" ] }, { "_id":"L215U3ViUmVhbG0", "_rev":"949061198", "parentPath":"/", "active":true, "name":"mySubRealm", "aliases":[ "payroll.example.com" ] } ], "resultCount":2, "pagedResultsCookie":null, "totalPagedResultsPolicy":"NONE", "totalPagedResults":-1, "remainingPagedResults":-1 } ``` For more information about using the `_queryString` parameter in REST calls, see [Query](../am-rest/rest-intro.html#about-crest-query). ### Read a realm To read a realm's details, send an HTTP GET to the `/json/global-config/realms/realm-id` endpoint, where `realm-id` is the value of `_id` for the realm. The following example shows an administrator receiving information about a realm called `mySubRealm`, which has an `_id` value of `L215U3ViUmVhbG0`: ```bash $ curl \ --header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \ --header "Accept-API-Version: resource=1.0" \ https://am.example.com:8443/am/json/global-config/realms/L215U3ViUmVhbG0 { "_id": "L215U3ViUmVhbG0", "_rev": "949061698", "parentPath": "/", "active": true, "name": "mySubRealm", "aliases": [ "payroll.example.com" ] } ``` AM returns a 200 HTTP status code and a JSON representation of the realm on success. On failure, AM returns a JSON representation of the error including the HTTP status code. For more information, see [HTTP Status Codes](../am-rest/rest-intro.html#about-crest-response-codes). ### Update a realm To update a realm's aliases or to toggle between active and inactive, send an HTTP PUT to the `/json/global-config/realms/realm-id` endpoint, where `realm-id` is the value of `_id` for the realm. The request should include an updated JSON representation of the complete realm. Note that you cannot alter the `name` or `parent` properties of a realm. The following example shows how to update a realm called `mySubRealm`, which has an `_id` value of `L215U3ViUmVhbG0`. The example changes the realm status to inactive: ```bash $ curl \ --request PUT \ --header "iPlanetDirectoryPro: AQIC5…​Y3MTAx*" \ --header "Content-Type: application/json" \ --header "Accept-API-Version: resource=1.0, protocol=1.0" \ --data '{ "parentPath": "/", "active": false, "name": "mySubRealm", "aliases": [ "payroll.example.com" ] }' \ https://am.example.com:8443/am/json/global-config/realms/L215U3ViUmVhbG0 { "_id": "L215U3ViUmVhbG0", "_rev": "94906213", "parentPath": "/", "active": false, "name": "mySubRealm", "aliases": [ "payroll.example.com" ] } ``` AM returns a 200 HTTP status code and a JSON representation of the realm on success. On failure, AM returns a JSON representation of the error including the HTTP status code. For more information, see [HTTP Status Codes](../am-rest/rest-intro.html#about-crest-response-codes). ### Delete a realm To delete a realm, perform an HTTP DELETE on the `/json/global-config/realms/realm-id` endpoint, where `realm-id` is the value of `_id` for the realm. The following example shows how to delete a realm called `mySubRealm`, which has an `_id` value of `L215U3ViUmVhbG0`. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Make sure that you do not have any information you need within a realm before deleting it. Once a realm is deleted, the only way to restore it is to return to a previously backed up deployment of AM. | ```bash $ curl \ --request DELETE \ --header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \ --header "Accept-API-Version: resource=1.0" \ https://am.example.com:8443/am/json/global-config/realms/L215U3ViUmVhbG0 { "_id": "L215U3ViUmVhbG0", "_rev": "949061708", "parentPath": "/", "active": false, "name": "mySubRealm", "aliases": [ "payroll.example.com" ] } ``` AM returns a 200 HTTP status code and a JSON representation of the deleted realm on success. On failure, AM returns a JSON representation of the error including the HTTP status code. For more information, [HTTP Status Codes](../am-rest/rest-intro.html#about-crest-response-codes).