diff --git a/docs/en/RefOverview.md b/docs/en/RefOverview.md index 6fb9583..3ed3ee8 100644 --- a/docs/en/RefOverview.md +++ b/docs/en/RefOverview.md @@ -35,6 +35,8 @@ Address all user-management requests to the UM API server: https://usermanagement.adobe.io/v2/usermanagement/... ``` +NOTE: In responses, as per the [HTTP specification](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers), HTTP header names are case insensitive. For example, x-current-page is identical to X-Current-Page. + ************ ### Summary of Actions on Users diff --git a/docs/en/api/ActionsCmds.md b/docs/en/api/ActionsCmds.md index 41003da..b240bce 100644 --- a/docs/en/api/ActionsCmds.md +++ b/docs/en/api/ActionsCmds.md @@ -379,7 +379,7 @@ Add or remove membership in administrative groups to control administrative righ * Support Administrators: `_support_admin` * Deployment Administrators: `_deployment_admin` - Please note that you cannot assign or remove the administrative role `_org_admin` using the User Management API. + Please note that you cannot assign or remove the administrative role `_org_admin`, `_compartment_admin` or `_compartment_viewer` using UMAPI. In addition, there are administrative groups for each user group and product profile. * An administrative group for a product is named with the prefix `_product_admin_` and the product name. For example, `_product_admin_Photoshop`. You should avoid any logic that expects fixed group names as these are liable to change without notice. @@ -402,11 +402,11 @@ Note that the response always reports a successful result for this action, even } ``` -* __deleteAccount:__ _boolean_; If true then if the account is owned by the organization, the account is also deleted. Note that [Adobe IDs](glossary.md#adobeId) are never deleted because they are owned by the user, not the organization. The default value is false. +* __deleteAccount:__ _boolean_; If true then if the account is owned by the organization, the account and any of their assets are also deleted. Note that [Adobe IDs](glossary.md#adobeId) are never deleted because they are owned by the user, not the organization. The default value is false. Corresponding Admin Console actions: * `"deleteAccount": false` = removing the user from the __Users__ menu -* `"deleteAccount": true` = removing the user from the __Directory users__ menu; implies loss of account metadata and associated cloud assets +* `"deleteAccount": true` = removing the user from the __Users__ menu AND the __Directory users__ menu. Removing users from a directory will permanently delete them and their assets. Use this feature with caution as the user and the assets cannot be recovered afterwards. Full information on removing users from a directory can be found [here](https://helpx.adobe.com/enterprise/using/manage-directory-users.html). Sample JSON body for email based login: diff --git a/docs/en/api/DeprecatedApis.md b/docs/en/api/DeprecatedApis.md index ed74f2a..d8fa1ce 100644 --- a/docs/en/api/DeprecatedApis.md +++ b/docs/en/api/DeprecatedApis.md @@ -9,7 +9,13 @@ lang: en # Deprecated APIs -The following APIs have been deprecated. These APIs will continue to function but could be removed at some point in the future. Their usage is strongly discouraged. Alternatives are noted below. +The following APIs have been deprecated. These APIs will continue to function but could be removed at some point in the future with appropriate notice. Their usage is strongly discouraged. Alternatives are noted below. + +**For the avoidance of doubt, all APIs provided by UMAPI, even those marked as deprecated will continue to be supported for the foreseeable future.** + +If it becomes apparent that any API, deprecated or otherwise, needs to be retired from service or needs updated with a breaking change, Adobe will provide at least 6 (six) months notice of the change, via UMAPI documentation (this site) and via Developer Console. + +Developer support will also work to make customers aware of the upcoming changes during their regular engagement. | Deprecated | Current | | :--- | :------ | @@ -20,4 +26,4 @@ The following APIs have been deprecated. These APIs will continue to function bu | [GET /v2/usermanagement/users/{orgId}/{page}/{groupName}](getUsersByGroup.md) | The `adminRoles` property is now deprecated, and administrative roles are reflected in group memberships, returned in the [`groups`](getUsersByGroup.md#ResponseProps) field. | {:.bordertablestyle} ->Please note that some additional properties can appear in a response but should not be relied upon. Only rely on those properties that are documented in the Response Properties section for each API. \ No newline at end of file +>Please note that some additional properties can appear in a response but should not be relied upon. Only rely on those properties that are documented in the Response Properties section for each API. diff --git a/docs/en/api/ErrorRef.md b/docs/en/api/ErrorRef.md index 4862cfe..4bf2403 100644 --- a/docs/en/api/ErrorRef.md +++ b/docs/en/api/ErrorRef.md @@ -405,4 +405,13 @@ The possible error codes and messages are listed with their context and descript * **error.usergroup.exceeds_maximum_member_count** * add, remove - * The current user count for the group exceeds the recommended size. Please refer to our [requesting help page](getsupport.html) if you would like to discuss this issue further. + * The current user count for the group exceeds the recommended size. Please refer to our [requesting help page](getSupport.html) if you would like to discuss this issue further. +* **error.usergroup.readonly.update_not_allowed** + * update + * Attempting to modify a readonly group e.g. update the group name +* **error.usergroup.readonly.add_user_not_allowed** + * add + * Attempting to add a user membership to a readonly group +* **error.usergroup.readonly.remove_user_not_allowed** + * remove + * Attempting to remove a user membership from a readonly group diff --git a/docs/en/api/QueryProducts.md b/docs/en/api/QueryProducts.md index f85ed92..b27c922 100644 --- a/docs/en/api/QueryProducts.md +++ b/docs/en/api/QueryProducts.md @@ -8,7 +8,7 @@ title: Product Access APIs --- # Product Access APIs -**DEPRECATED:** These APIs have been deprecated. An exact date for removal will be confirmed before the end of 2017 but you should look to update your scripts as soon as possible. +**DEPRECATED:** These APIs have been deprecated. Please use [Get User Groups and Product Profiles](group.md).
diff --git a/docs/en/api/QueryUserGroups.md b/docs/en/api/QueryUserGroups.md index 7d66633..ea98603 100644 --- a/docs/en/api/QueryUserGroups.md +++ b/docs/en/api/QueryUserGroups.md @@ -8,7 +8,7 @@ title: Get User Group Users --- # Get User-group Users -**DEPRECATED:** These APIs have been deprecated. An exact date for removal will be confirmed before the end of 2017 but you should look to update your scripts as soon as possible. +**DEPRECATED:** These APIs have been deprecated. Please use [Get Users by Group API](getUsersByGroup.md) for fetching information for a single group.
diff --git a/docs/en/api/getAllProfilesForOrg.md b/docs/en/api/getAllProfilesForOrg.md index 1a8d782..6121a86 100644 --- a/docs/en/api/getAllProfilesForOrg.md +++ b/docs/en/api/getAllProfilesForOrg.md @@ -9,7 +9,7 @@ nav_link: Get All Profiles # Get All Product Profiles for Organization -**DEPRECATED:** These APIs have been deprecated. An exact date for removal will be confirmed before the end of 2017 but you should look to update your scripts as soon as possible. +**DEPRECATED:** These APIs have been deprecated. Please use [Get User Groups and Product Profiles](group.md).
diff --git a/docs/en/api/getProductProfile.md b/docs/en/api/getProductProfile.md index d9235b0..08d7ed1 100644 --- a/docs/en/api/getProductProfile.md +++ b/docs/en/api/getProductProfile.md @@ -8,7 +8,7 @@ lang: en --- # Get Product Profile -**DEPRECATED:** These APIs have been deprecated. An exact date for removal will be confirmed before the end of 2017 but you should look to update your scripts as soon as possible. +**DEPRECATED:** These APIs have been deprecated. Please use [Get Users by Group API](getUsersByGroup.md) for fetching information for a single product profile.
``` diff --git a/docs/en/api/getProductProfileUsers.md b/docs/en/api/getProductProfileUsers.md index 21f21ed..ad2a01b 100644 --- a/docs/en/api/getProductProfileUsers.md +++ b/docs/en/api/getProductProfileUsers.md @@ -8,7 +8,7 @@ lang: en --- # Get Users in Product Profile -**DEPRECATED:** These APIs have been deprecated. An exact date for removal will be confirmed before the end of 2017 but you should look to update your scripts as soon as possible. +**DEPRECATED:** These APIs have been deprecated. Please use [Get Users by Group API](getUsersByGroup.md) for fetching users of a product profile.
diff --git a/docs/en/api/getUser.md b/docs/en/api/getUser.md index 2232c2b..bc4e519 100644 --- a/docs/en/api/getUser.md +++ b/docs/en/api/getUser.md @@ -24,10 +24,10 @@ __Throttle Limits__: Maximum 25 requests per minute per a client. See [Throttlin | Name | Type | Req? | Description | | :---- | :--- | :---: | :------ | | orgId | path | true | {% include_relative partials/orgIdDescription.md %} | -| userString | path | true | For [AdobeID](glossary.md#adobeId), [Enterprise](glossary.md#enterpriseId) and _[email-federated](glossary.md#federatedId)_ users this should be the full email address including domain. In all cases the parameter is case-insensitive. [Identity Types](glossary.md#identity) explains the different account types available. | +| userString | path | true | For [AdobeID](glossary.html#adobeId), [Enterprise](glossary.html#enterpriseId) and _[email-federated](glossary.html#federatedId)_ users this should be the full email address including domain. In all cases the parameter is case-insensitive. [Identity Types](glossary.html#identity) explains the different account types available. | | X-Api-Key | header | true | {% include_relative partials/apiKeyDescription.md %} | | Authorization | header | true | {% include_relative partials/authorizationDescription.md %} | -| domain | query | false | Optional parameter but highly recommended including for all user types. For [AdobeID](glossary.md#adobeId) users this would be `AdobeID`. For [Enterprise](glossary.md#enterpriseId) and _[email-federated](glossary.md#federatedId)_ users the domain will either match the email domain or, in the case of multi-domain federations, have any other domain for that directory. | +| domain | query | false | Optional parameter but highly recommended including for all user types. For [AdobeID](glossary.html#adobeId) users this would be `AdobeID`. For [Enterprise](glossary.html#enterpriseId) and _[email-federated](glossary.html#federatedId)_ users the domain will either match the email domain or, in the case of multi-domain federations, have any other domain for that directory. | | content-type | header | false | {% include_relative partials/contentTypeDescription.md %} | | X-Request-Id | header | false | {% include_relative partials/requestIdDescription.md %} | {:.bordertablestyle} @@ -47,7 +47,7 @@ __Content-Type:__ _application/json_ ### 200 OK The response body contains the requested user data in JSON format including any of the user's group membership and admin roles. Fields can be missing if values were never supplied or are not applicable for a particular account type. -[Identity Types](glossary.md#identity) explains the different account types available. +[Identity Types](glossary.html#identity) explains the different account types available. ### Examples Response for an Adobe ID user with System Administrator role: @@ -65,14 +65,12 @@ The response body contains the requested user data in JSON format including any "type": "adobeID", "groups": [ "_org_admin" - ], - "tags": [ - "edu_student" ] } } ``` -[Enterprise](glossary.md#enterpriseId) User with membership in two user-groups but no administrative roles. If the fields are not populated (`firstname` and`lastname` in this example), they are excluded from the response. + +[Enterprise](glossary.html#enterpriseId) User with membership in two user-groups but no administrative roles. If the fields are not populated (`firstname` and`lastname` in this example), they are excluded from the response. ```json { "result": "success", @@ -90,7 +88,7 @@ The response body contains the requested user data in JSON format including any } } ``` -[Federated](glossary.md#federatedId) User with no memberships or administrative roles: +[Federated](glossary.html#federatedId) User with no memberships or administrative roles: ```json { "result": "success", @@ -140,10 +138,7 @@ __user:__ A _user_ object containing relevant properties. Properties that are n "lastname": "string", "status": "string", "type": "string", - "username": "string", - "tags": [ - "string" - ] + "username": "string" } } ``` @@ -157,19 +152,19 @@ __user:__ A _user_ object containing relevant properties. Properties that are n {% include_relative partials/notFound.md object="user" anchor="404getUser" %} ## Example Requests -Searching by email for [AdobeID](glossary.md#adobeId), [Enterprise](glossary.md#enterpriseId) or [email-federated](glossary.md#federatedId) users: +Searching by email for [AdobeID](glossary.html#adobeId), [Enterprise](glossary.html#enterpriseId) or [email-federated](glossary.html#federatedId) users: ``` curl -X GET https://usermanagement.adobe.io/v2/usermanagement/organizations/12345@AdobeOrg/users/jdoe@example.com \ --header 'Authorization: Bearer ey...' \ --header 'X-Api-Key: 88ce03094fe74f4d91c2538217d007fe' ``` -Searching for [AdobeID](glossary.md#adobeId) user with domain: +Searching for [AdobeID](glossary.html#adobeId) user with domain: ``` curl -X GET https://usermanagement.adobe.io/v2/usermanagement/organizations/12345@AdobeOrg/users/jdoe@example.com?domain=AdobeID \ --header 'Authorization: Bearer ey...' \ --header 'X-Api-Key: 88ce03094fe74f4d91c2538217d007fe' ``` - Searching for [Enterprise](glossary.md#enterpriseId) or [email-federated](glossary.md#federatedId) users with domain parameter included: + Searching for [Enterprise](glossary.html#enterpriseId) or [email-federated](glossary.html#federatedId) users with domain parameter included: ``` curl -X GET https://usermanagement.adobe.io/v2/usermanagement/organizations/12345@AdobeOrg/users/jdoe@example.com?domain=example.com \ --header 'Authorization: Bearer ey...' \ diff --git a/docs/en/api/getUserGroup.md b/docs/en/api/getUserGroup.md index 0134bcf..e2a04e0 100644 --- a/docs/en/api/getUserGroup.md +++ b/docs/en/api/getUserGroup.md @@ -9,7 +9,7 @@ lang: en # Get User Group -**DEPRECATED:** These APIs have been deprecated. An exact date for removal will be confirmed before the end of 2017 but you should look to update your scripts as soon as possible. +**DEPRECATED:** These APIs have been deprecated. Please use [Get Users by Group API](getUsersByGroup.md) for fetching information for a single group.
@@ -62,7 +62,8 @@ The response body contains the specified user-group in JSON format including the "adminGroupId": "42073423", "adminGroupName": "39127441USERGROUP_ADMIN_GROUP_NAME_SUFFIX", "userCount": 2, - "adminCount": "1" + "adminCount": "1", + "isReadOnly": false } ``` @@ -85,6 +86,9 @@ The group type which will always be `USER_GROUP`. __userCount:__ _integer_ The number of users in the group. +__isReadOnly:__ _boolean_ +Indicates if it is possible to directly add and remove users from the group. Groups shared from another organization will return true otherwise it will return false or not be present if not applicable. Further information is available at [Share User Groups](https://www.adobe.com/go/user_group_share) + #### Schema Model ```json @@ -95,7 +99,8 @@ The number of users in the group. "groupId": integer, "name": "string", "type": "string", - "userCount": integer + "userCount": integer, + "isReadOnly": boolean } ``` diff --git a/docs/en/api/getUserGroups.md b/docs/en/api/getUserGroups.md index 3b49a76..48a3364 100644 --- a/docs/en/api/getUserGroups.md +++ b/docs/en/api/getUserGroups.md @@ -8,7 +8,7 @@ lang: en --- # Get User Groups -**DEPRECATED:** These APIs have been deprecated. An exact date for removal will be confirmed before the end of 2017 but you should look to update your scripts as soon as possible. +**DEPRECATED:** These APIs have been deprecated. Please use [Get User Groups and Product Profiles](group.md).
@@ -75,7 +75,8 @@ Response with 3 user-groups including a user-group with administrators. "groupId": 44815360, "name": "UserGroup12", "type": "USER_GROUP", - "userCount": 1 + "userCount": 1, + "isReadOnly": true }, { "groupId": 44382376, @@ -106,6 +107,9 @@ The group type will always be `USER_GROUP`. __userCount:__ _long_ The number of users in the group. {% include_relative partials/mayNotBePresent.md %} +__isReadOnly:__ _boolean_ +Indicates if it is possible to directly add and remove users from the group. Further information is available at [Share User Groups](https://www.adobe.com/go/user_group_share) + #### Schema Model ```json diff --git a/docs/en/api/getUsersByGroup.md b/docs/en/api/getUsersByGroup.md index f5462f6..988827d 100644 --- a/docs/en/api/getUsersByGroup.md +++ b/docs/en/api/getUsersByGroup.md @@ -36,6 +36,7 @@ __Throttle Limits__: Maximum 25 requests per minute per a client. See [Throttlin | X-Request-Id | header | false | {% include_relative partials/requestIdDescription.md %} | | directOnly | query | false | {% include_relative partials/directOnlyDescription.md %} | | status | query | false | For product profiles only, return only active or inactive members. Pass `active` to list users that have been provisioned for the product and have an active license. Pass `inactive` to list users who have been added to the product profile but do not have an _active_ license. When not provided, lists all member users regardless of their entitlement status.| +| excludeGroups | query | false | Default value is `false`. When `true` is passed the response will exclude the `groups` array from being returned for each individual user. See [example](#getUsersWithNoGroupsExample). | {:.bordertablestyle} ## Responses @@ -78,10 +79,7 @@ A successful request returns a response body with the requested user data in JSO "username": "john", "domain": "example.com", "country": "US", - "type": "federatedID", - "tags": [ - "edu_student" - ] + "type": "federatedID" }, { "email": "jane@example.com", @@ -118,6 +116,43 @@ A successful request returns a response body with the requested user data in JSO } ``` +Response returning three members of the Document Cloud 1 group. The `groups` array for each user has been excluded in the response as the query parameter `excludeGroups=true` was included: + +```json +{ + "lastPage": false, + "result": "success", + "groupName": "Document Cloud 1", + "users": [ + { + "email": "john@example.com", + "status": "active", + "username": "john", + "domain": "example.com", + "country": "US", + "type": "federatedID" + }, + { + "email": "jane@example.com", + "status": "active", + "username": "jane", + "domain": "example.com", + "country": "US", + "type": "federatedID" + }, + { + "email": "bob@example.com", + "status": "active", + "username": "bob", + "domain": "example.com", + "country": "US", + "type": "federatedID" + } + ... + ] +} +``` + Response to request for the last page: ```json @@ -178,10 +213,7 @@ __users:__ Contains a list of _User_ objects. Properties that are not populated "lastname": "string", "status": "string", "type": "string", - "username": "string", - "tags": [ - "string" - ] + "username": "string" } ] } diff --git a/docs/en/api/getUsersREST.md b/docs/en/api/getUsersREST.md index bbafa27..43ab217 100644 --- a/docs/en/api/getUsersREST.md +++ b/docs/en/api/getUsersREST.md @@ -9,7 +9,7 @@ lang: en # Get All Users in Organization -**DEPRECATED:** These APIs have been deprecated. An exact date for removal will be confirmed before the end of 2017 but you should look to update your scripts as soon as possible. +**DEPRECATED:** These APIs have been deprecated. Please use [Get Users in Organization](getUsersWithPage.md)
diff --git a/docs/en/api/getUsersWithPage.md b/docs/en/api/getUsersWithPage.md index d2c7daa..2c0d435 100644 --- a/docs/en/api/getUsersWithPage.md +++ b/docs/en/api/getUsersWithPage.md @@ -72,10 +72,7 @@ A successful request returns a response body with the requested user data in JSO "username": "psmith", "domain": "example.com", "country": "US", - "type": "federatedID", - "tags": [ - "edu_student" - ] + "type": "federatedID" }, { "email": "jane@example.com", @@ -120,6 +117,8 @@ A successful request returns a response body with the requested user data in JSO ] } ``` +:warning: As of October 16, 2025, the `tags` array will no longer be returned. + Response that is the last page: ```json { @@ -183,6 +182,8 @@ __users:__ Contains a list of _User_ objects. Properties that are not populated } ``` +:warning: As of October 16, 2025, the `tags` array will no longer be returned. + {% include_relative partials/badRequest.md anchor="400getUsersWithPage" %} {% include_relative partials/unauthorized.md anchor="401getUsersWithPage" %} diff --git a/docs/en/api/glossary.md b/docs/en/api/glossary.md index 7ec07eb..2d63df0 100644 --- a/docs/en/api/glossary.md +++ b/docs/en/api/glossary.md @@ -11,26 +11,27 @@ lang: en The following table defines common terms used throughout the User Management API documentation: -| Term | Meaning | -| :---- | :--------------- | -| Access Token | {% include_relative partials/authorizationDescription.md %} | -| Admin Console | A central location for managing your Adobe entitlements across your entire organization, available at https://adminconsole.adobe.com/enterprise. | -| AdobeID | An Identity Type that is created, owned, and managed by the end user. Adobe performs authentication, and the end user manages the identity. Users retain complete control over files and data associated with their ID. See full discussion at [Identity Types](https://helpx.adobe.com/enterprise/help/identity.html). | -| API Key | {% include_relative partials/apiKeyDescription.md %} | -| Deployment Administrator | Creates, manages, and deploys software packages and updates to end users. See full discussion at [Administrative Roles](https://helpx.adobe.com/enterprise/using/admin-roles.html#).| -| Developer | Users given this role for a specific product profile are considered to be a developer for that product profile. See full discussion at [Administrative Roles](https://helpx.adobe.com/enterprise/using/admin-roles.html#).| -| Enterprise ID | An Identity Type that is created, owned, and managed by an organization. Adobe hosts the Enterprise ID and performs authentication, but the organization maintains the Enterprise ID. End-users cannot sign up and create an Enterprise ID, nor can they sign up for additional products and services from Adobe using an Enterprise ID. See full discussion at [Identity Types](https://helpx.adobe.com/enterprise/help/identity.html). | -| Federated ID | An Identity Type that is created and owned by an organization, and linked to the enterprise directory through federation. The organization manages credentials and processes Single Sign-On through a SAML2 identity provider. UMAPI clients with email-federated domains must always identity users by email. See full discussion at [Identity Types](https://helpx.adobe.com/enterprise/help/identity.html). | -| usertype `unknown` | In some cases a userType may contain the value `unknown`. In these cases the user may not contain the necessary values to identify the user type.| -| Group type | The group type is returned in user-group API responses. User-groups are always of type `USER_GROUP` | -| Identity Types | The [Identity Types](https://helpx.adobe.com/enterprise/help/identity.html) resource explains the different account types that are available: Adobe, Enterprise, and Federated IDs. | -| Organization ID | {% include_relative partials/orgIdDescription.md %} | -| Product Administrator | A user role in an organization. A user with this role (an admin) administers the assigned products, managing all associated administrative functions, such as creating product profiles and adding users and user-groups to the organization. See full discussion at [Administrative Roles](https://helpx.adobe.com/enterprise/using/admin-roles.html#). | -| Product Profile | A set of specific entitlements and roles for a product, defined in the Admin Console. Users and user groups can belong to product profiles. | -| Product Profile Administrator | A user role in an organization. A user with this role administers assigned Product Profile descriptions, managing all associated administrative functions, such as adding and removing users from Product Profiles. See full discussion at [Administrative Roles](https://helpx.adobe.com/enterprise/using/admin-roles.html#). | -| System Administrator | A user role in an organization. A "super user" for the organization who is allowed to perform all administrative tasks, including the capabilities granted to User Group admin, Product admin, Product Profile admin, Support admin and Deployment admin. See full discussion at [Administrative Roles](https://helpx.adobe.com/enterprise/using/admin-roles.html#). | -| Support Administrator | See full discussion at [Administrative Roles](https://helpx.adobe.com/enterprise/using/admin-roles.html#). | -| User Group | A group of loosely associated users. Typically used to organize a set of related users by department or function. For example: `U.S.FinanceOperations`, `EU Human Resources` | -| User-group ID | A unique Adobe-assigned number used to identify a user-group. For examples, `46842488`| -| User-group Administrator | A user role in an organization. Administers assigned user-group descriptions, managing all associated administrative functions, such as adding and removing users from groups. See full discussion at [Administrative Roles](https://helpx.adobe.com/enterprise/using/admin-roles.html#). | +| Term | Meaning | +|:-----------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Access Token | {% include_relative partials/authorizationDescription.md %} | +| Admin Console | A central location for managing your Adobe entitlements across your entire organization, available at https://adminconsole.adobe.com/enterprise. | +| AdobeID | An Identity Type that is created, owned, and managed by the end user. Adobe performs authentication, and the end user manages the identity. Users retain complete control over files and data associated with their ID. See full discussion at [Identity Types](https://helpx.adobe.com/enterprise/help/identity.html). | +| API Key | {% include_relative partials/apiKeyDescription.md %} | +| Deployment Administrator | Creates, manages, and deploys software packages and updates to end users. See full discussion at [Administrative Roles](https://helpx.adobe.com/enterprise/using/admin-roles.html#). | +| Developer | Users given this role for a specific product profile are considered to be a developer for that product profile. See full discussion at [Administrative Roles](https://helpx.adobe.com/enterprise/using/admin-roles.html#). | +| Enterprise ID | An Identity Type that is created, owned, and managed by an organization. Adobe hosts the Enterprise ID and performs authentication, but the organization maintains the Enterprise ID. End-users cannot sign up and create an Enterprise ID, nor can they sign up for additional products and services from Adobe using an Enterprise ID. See full discussion at [Identity Types](https://helpx.adobe.com/enterprise/help/identity.html). | +| Federated ID | An Identity Type that is created and owned by an organization, and linked to the enterprise directory through federation. The organization manages credentials and processes Single Sign-On through a SAML2 identity provider. UMAPI clients with email-federated domains must always identity users by email. See full discussion at [Identity Types](https://helpx.adobe.com/enterprise/help/identity.html). | +| usertype `unknown` | In some cases a userType may contain the value `unknown`. In these cases the user may not contain the necessary values to identify the user type. | +| Group type | The group type is returned in user-group API responses. User-groups are always of type `USER_GROUP` | +| Identity Types | The [Identity Types](https://helpx.adobe.com/enterprise/help/identity.html) resource explains the different account types that are available: Adobe, Enterprise, and Federated IDs. | +| Organization ID | {% include_relative partials/orgIdDescription.md %} | +| Product Administrator | A user role in an organization. A user with this role (an admin) administers the assigned products, managing all associated administrative functions, such as creating product profiles and adding users and user-groups to the organization. See full discussion at [Administrative Roles](https://helpx.adobe.com/enterprise/using/admin-roles.html#). | +| Product Profile | A set of specific entitlements and roles for a product, defined in the Admin Console. Users and user groups can belong to product profiles. | +| Product Profile Administrator | A user role in an organization. A user with this role administers assigned Product Profile descriptions, managing all associated administrative functions, such as adding and removing users from Product Profiles. See full discussion at [Administrative Roles](https://helpx.adobe.com/enterprise/using/admin-roles.html#). | +| System Administrator | A user role in an organization. A "super user" for the organization who is allowed to perform all administrative tasks, including the capabilities granted to User Group admin, Product admin, Product Profile admin, Support admin and Deployment admin. See full discussion at [Administrative Roles](https://helpx.adobe.com/enterprise/using/admin-roles.html#). | +| Support Administrator | See full discussion at [Administrative Roles](https://helpx.adobe.com/enterprise/using/admin-roles.html#). | +| User Group | A group of loosely associated users. Typically used to organize a set of related users by department or function. For example: `U.S.FinanceOperations`, `EU Human Resources` | +| User-group ID | A unique Adobe-assigned number used to identify a user-group. For examples, `46842488` | +| User-group Administrator | A user role in an organization. Administers assigned user-group descriptions, managing all associated administrative functions, such as adding and removing users from groups. See full discussion at [Administrative Roles](https://helpx.adobe.com/enterprise/using/admin-roles.html#). | +| Shared User Group | In the Global Admin Console, Shared user groups allows you to use a single user management source to sync user groups and the associated users to multiple Admin Consoles. Further information available at [Share User Groups](https://www.adobe.com/go/user_group_share) | {:.bordertablestyle} diff --git a/docs/en/api/partials/badRequest.md b/docs/en/api/partials/badRequest.md index 5063981..ee9b437 100644 --- a/docs/en/api/partials/badRequest.md +++ b/docs/en/api/partials/badRequest.md @@ -11,4 +11,142 @@ Possible cause: < Canonical-Resource: /v2/usermanagement/users/{orgId}/{page}/{groupName} {"errorMessage":"DUPLICATE_GROUP_NAME","errorCode":"DUPLICATE_GROUP_NAME"} ``` + +- Attempting to modify a readonly group e.g. update the group name + +``` +> v2/usermanagement/action/56EB197B663A09470A494111@AdobeOrg HTTP/1.1 +> [ +> { +> "usergroup": "UMAPI Test", +> "do": [ +> { +> "updateUserGroup": { +> "name": "UMAPI Test Updated" +> } +> } +> ] +> } +> ] +< Canonical-Resource: /v2/usermanagement/action/{orgId} +< { +< "completed": 0, +< "notCompleted": 1, +< "completedInTestMode": 0, +< "result": "error", +< "errors": [ +< { +< "index": 0, +< "step": 0, +< "message": "Usergroup is owned by another org and readonly: UMAPI Test", +< "errorCode": "error.usergroup.readonly.update_not_allowed", +< "user": "UMAPI Test" +< } +< ] +< } +``` + +- Attempting to add a user membership of a readonly group + +``` +> POST v2/usermanagement/action/56EB197B663A09470A494111@AdobeOrg HTTP/1.1 +> [ +> { +> "usergroup": "UMAPI Test", +> "do": [ +> { +> "add": { +> "user": [ +> "test@user.com" +> ] +> } +> } +> ] +> } +> ] +< Canonical-Resource: /v2/usermanagement/action/{orgId} +< { +< "completed": 0, +< "notCompleted": 1, +< "completedInTestMode": 0, +< "result": "error", +< "errors": [ +< { +< "index": 0, +< "step": 0, +< "message": "User cannot be added to group as owned by another org and readonly: UMAPI Test", +< "errorCode": "error.usergroup.readonly.add_user_not_allowed", +< "user": "UMAPI Test" +< } +< ] +< } +``` + +- Attempting to remove a user membership of a readonly group + +``` +> POST v2/usermanagement/action/56EB197B663A09470A494111@AdobeOrg HTTP/1.1 +> [ +> { +> "usergroup": "UMAPI Test", +> "do": [ +> { +> "remove": { +> "user": [ +> "test@user.com" +> ] +> } +> } +> ] +> } +> ] +< Canonical-Resource: /v2/usermanagement/action/{orgId} +< { +< "completed": 0, +< "notCompleted": 1, +< "completedInTestMode": 0, +< "result": "error", +< "errors": [ +< { +< "index": 0, +< "step": 0, +< "message": "User cannot be removed from group as owned by another org and readonly: UMAPI Test", +< "errorCode": "error.usergroup.readonly.remove_user_not_allowed", +< "user": "UMAPI Test" +< } +< ] +< } +``` + +- Attempting to remove a readonly group from the organization + +``` +> POST v2/usermanagement/action/56EB197B663A09470A494111@AdobeOrg HTTP/1.1 +> [ +> { +> "usergroup": "UMAPI Test", +> "do": [ +> { +> "deleteUserGroup": {} +> } +> ] +> } +> ] +< Canonical-Resource: /v2/usermanagement/action/{orgId} +< { +< "completed": 0, +< "notCompleted": 1, +< "completedInTestMode": 0, +< "result": "error", +< "errors": [ +< { +< "index": 0, +< "step": 0, +< "message": "User group owned by another organization. Remove not allowed: UMAPI Test", +< "errorCode": "error.usergroup.readonly.remove_not_allowed", +< "user": "UMAPI Test" +< } +< ] +< } +``` {% endif %} diff --git a/docs/en/api/partials/directOnlyDescription.md b/docs/en/api/partials/directOnlyDescription.md index 3c1121e..4a95b68 100644 --- a/docs/en/api/partials/directOnlyDescription.md +++ b/docs/en/api/partials/directOnlyDescription.md @@ -1 +1 @@ -Controls whether the `groups` field in the returned user structure contains only those product profiles of which that user is a direct member. If false, returns all groups (user groups, product profiles, and admin groups) containing the user, regardless of whether an entitlement for a particular product profile comes directly (via user assignment) or indirectly (via a user group that contains the user being assigned to the product profile). If true, returns all user groups and admin groups containing the user, but only those product profiles to which the user has been explicitly assigned an entitlement. A user can be both a direct and an indirect member of a product profile. \ No newline at end of file +Controls whether the `groups` field in the returned user structure contains only those product profiles of which that user is a direct member. If false, returns all groups (user groups, product profiles, and admin groups) containing the user, regardless of whether an entitlement for a particular product profile comes directly (via user assignment) or indirectly (via a user group that contains the user being assigned to the product profile). If true, returns all user groups and admin groups containing the user, but only those product profiles to which the user has been explicitly assigned an entitlement. A user can be both a direct and an indirect member of a product profile. Defaults to `true`. diff --git a/docs/en/api/partials/userSchemaDescription.md b/docs/en/api/partials/userSchemaDescription.md index 5d717a6..6951680 100644 --- a/docs/en/api/partials/userSchemaDescription.md +++ b/docs/en/api/partials/userSchemaDescription.md @@ -15,5 +15,4 @@ * "removed": The user account is being removed. * __type:__ _string_, The user type, one of: `{ "adobeID", "enterpriseID", "federatedID", "unknown" }`. See [Identity Types](glossary.md#identity) for more information. * __username:__ _string_; The user's username (applicable for [Enterprise](glossary.md#enterpriseId) and [Federated](glossary.md#federatedId) users). For most [Adobe ID](glossary.md#adobeId) users, this value is the same as the email address. -* __tags:__ _string[]_; Returns a list of the tags applied to a user e.g. `["edu_student", "edu_staff"]`. This will not be returned if the user has no tags. * **adminRoles:** _string[]_; Deprecated. Administrative roles are reflected in group memberships, returned in the `groups` field. \ No newline at end of file diff --git a/docs/en/api/product.md b/docs/en/api/product.md index 50569fc..51f104d 100644 --- a/docs/en/api/product.md +++ b/docs/en/api/product.md @@ -8,7 +8,7 @@ lang: en --- # Product Information APIs -**DEPRECATED:** These APIs have been deprecated. An exact date for removal will be confirmed before the end of 2017 but you should look to update your scripts as soon as possible. +**DEPRECATED:** These APIs have been deprecated and are unsupported. Please refer to [Get User Groups and Product Profiles](group.md) instead.
diff --git a/docs/en/api/updateProductProfile.md b/docs/en/api/updateProductProfile.md index dd8dc14..035489e 100644 --- a/docs/en/api/updateProductProfile.md +++ b/docs/en/api/updateProductProfile.md @@ -8,7 +8,7 @@ lang: en --- # Update Product Profile -**DEPRECATED:** These APIs have been deprecated. An exact date for removal will be confirmed before the end of 2017 but you should look to update your scripts as soon as possible. +**DEPRECATED:** These APIs have been deprecated. Please refer to the [User Management Action API](ActionsRef.md) for details on the supported approach to assign and manage membership and administrative rights within your Organization.
diff --git a/docs/en/api/usergroupActionCommands.md b/docs/en/api/usergroupActionCommands.md index d570d17..0c02daa 100644 --- a/docs/en/api/usergroupActionCommands.md +++ b/docs/en/api/usergroupActionCommands.md @@ -75,6 +75,8 @@ When you remove a user from the group, that user loses the associated entitlemen * When you add a product profile, all of the member users gain the associated entitlements. When you remove a product profile, all of the users in the user group lose the associated entitlements (unless they have individual access). Please note that you cannot use the add command if the user-group has more than 200,000 users. +* When a group has `isReadOnly` set to true, you cannot add or remove users from the group however you can add or remove product profiles. + >NOTE: Use the [`group`](group.md) resource to retrieve information about defined groups. Each step can add or remove up to 10 memberships in one command entry using the `user` and `productConfiguration` options. Specify users by email, and product profiles by name. diff --git a/docs/en/getstarted.md b/docs/en/getstarted.md index d27b697..850484b 100644 --- a/docs/en/getstarted.md +++ b/docs/en/getstarted.md @@ -9,10 +9,11 @@ lang: en {% include_relative partials/umIntro.md %} -The User Management API allows you to manage a large number of identities programmatically, rather than individually through a user interface. You can create programs that obtain account management data stored in another identity tool that you might already be using, such as Microsoft Active Directory, and can use that data in calls to the Adobe User Management API. You can call the API directly to perform creation, management, and removal of user accounts. You can also generate reports, or drive other processes that track which users have access to which Adobe products. +The User Management API (UMAPI) allows you to manage a large number of identities programmatically, rather than individually through a user interface. You can create programs that obtain account management data stored in another identity tool that you might already be using, such as Microsoft Active Directory, and can use that data in calls to the API. You can call the API directly to perform creation, management, and removal of user accounts. You can also generate reports, or drive other processes that track which users have access to which Adobe products. -You can use the API directly to create applications and scripts to manage your organization's Adobe user accounts and product entitlements. In addition to direct programmatic access through the API, Adobe offers system administrators a ready-made user-management automation tool, [User Sync](#usersync), which is built on top of the UM API. +You can use the API directly to create applications and scripts to manage your organization's Adobe user accounts and product entitlements. In addition to direct programmatic access through the API, Adobe offers system administrators a ready-made user-management automation tool, [User Sync](#usersync), which is built on top of UMAPI. +Note, however, that you cannot use UMAPI to add or remove users if you are using the [Azure/Entra](https://helpx.adobe.com/enterprise/using/add-azure-sync.html) or [Google](https://helpx.adobe.com/enterprise/using/setup-sso-google.html) automated sync processes in Admin Console. ## User Management Tasks diff --git a/docs/en/index.md b/docs/en/index.md index 76baf74..c146757 100644 --- a/docs/en/index.md +++ b/docs/en/index.md @@ -9,8 +9,64 @@ lang: en Welcome to the documentation center for User Management APIs from Adobe. -News: +

News

+

Feb 6, 2026: The fix from Feb 3 to correctly resolve user type as `unknown` when the account shows as "Not available" in Admin Console has been reverted due to an issue impacting User Sync Tool customers. A new date for this fix will be announced in the near future.

+
+

Feb 3, 2026: Deployment scheduled to fix the wrong identity type showing for impacted Business IDs that lost their auth account through permanent removal in the main (domain owning) Organisation. The previous type was showing "adobeID" and now it shows "unknown". +If an extraction of users in the Admin Console is made, then the resulting csv will show the impacted accounts on the Identity type column the question mark sign, instead of one of the known identity types: Adobe ID, Federated ID, Enterprise ID. +

+

October 27, 2025: As previously notified, UMAPI no longer returns "tags" information for the following APIs:

+ +

All references to this field have been removed from the relevant documentation.

+
+

July 23, 2025: We've been made aware that some customers are receiving group names with a mysterious suffix, such as provisioning. Since these groups or profiles with these names don't exist in Admin Console (they were a historic construct from a previous iteration of the Adobe platform), we will ensure that we fully filter out these mystery group names. APIs that return lists of group names will be changed to return only user group and product profile names that really exist in the org.

+

As a best practice, it is recommended to avoid any logic that expects fixed names.

+

This change will come into effect on August 26 September 23, 2025 October 28, 2025.

+
+

May 22, 2025: With the introduction of the Contract Admin role in 2024, we've been made aware that some customers are not receiving a type value from the Get User Groups and Product Profiles API. To help with consistency, we'll ensure that this scenario results in a type of CONTRACT_ADMIN_GROUP and will enhance the response with a contractName field as below:

+
+    {
+      "groupId": 555555555,
+      "groupName": "BCDEFA3F5A9DB8F0345B_CONTRACT_GROUP",
+      "adminGroupName": "_admin_BCDEFA3F5A9DB8F0345B_CONTRACT_GROUP",
+      "type": "CONTRACT_ADMIN_GROUP",
+      "contractName": "ETLA - BCDEFA3F5A9DB8F0345B",
+      "memberCount": 1
+    }
+
+

This change will come into effect on June 3, 2025.

+
+

May 9, 2025: With the introduction of Single App Edition 4, we've been made aware that some customers have both Single App and Single App Edition 4. To help distinguish groups for each Single App using the same infix structure introduced in May 2023, the `productName` field for the profile will be adjusted to return the "parent" product name, as in the below examples:

+ +

If you rely on the name of the "product admin group", you will also see a change here.

+

This change will come into effect on June 10, 2025.

+
+

April 15, 2025: As of October 16, 2025, UMAPI will no longer return "tags" information as documented for the following APIs:

+ +

Note that this data is likely to become stale over the coming months as the attribute is deprecated internally. If you are currently using this information, please get in touch with the developer support team to let us know your use case. Note that as this change is due to the data being retired from the Adobe platform, UMAPI will not be able to offer extensions to this time frame.

+
+

July 22, 2024: To provide peace of mind for API integrations, all APIs provided by UMAPI, even those marked as deprecated will continue to be supported for the foreseeable future.

+

If it becomes apparent that any API, deprecated or otherwise, needs to be retired from service or needs updated with a breaking change, Adobe will provide at least 6 (six) months notice of the change, via UMAPI documentation (this site) and via Developer Console banners.

+

We will also endeavour to provide 4 weeks notice of any new fields that are being added to responses in order to give time to prepare. As ever, guidance is to ignore any unrecognised or unknown fields in the UMAPI response. Unless it is documented, it should not be relied upon.

+

Developer support will also work to make customers aware of the upcoming removal of APIs during their regular engagement process. +

+
+

From Jan 16th 2024, a new query parameter excludeGroups will be available in Get Users by Group to exclude the return of other group membership information for each user.

+

Further information and examples can be found within the API documentation.

+

This does not impact existing clients.

+

From July 25th 2023, a new tags property will be returned as part of a user's response in the following APIs: