diff --git a/docs/en/api/ActionsCmds.md b/docs/en/api/ActionsCmds.md index c1ecee0..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. 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/getUsersByGroup.md b/docs/en/api/getUsersByGroup.md index ebe373b..988827d 100644 --- a/docs/en/api/getUsersByGroup.md +++ b/docs/en/api/getUsersByGroup.md @@ -79,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", @@ -133,10 +130,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", @@ -219,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/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/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/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 24b7ebc..c146757 100644 --- a/docs/en/index.md +++ b/docs/en/index.md @@ -11,7 +11,53 @@ Welcome to the documentation center for User Management APIs from Adobe.

News

-

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.

+

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. @@ -33,7 +79,7 @@ Welcome to the documentation center for User Management APIs from Adobe.

If you rely on the name of the “product admin group” (e.g., _product_admin_<product name>) you will also be impacted and have to update your scripts.

You should avoid any logic that expects fixed group names as these are liable to change without notice. We recommend using the Get Groups and Profiles API to fetch the latest group information.

-

Since May 6th, 2023, User Management API supports OAuth Server-to-Server (S2S) workflows; The JWT one is deprecated and will be removed on 1st of January 2025. Existing integrations based on this authorization scheme will continue to work as usual until this date. Please migrate your project to use OAuth S2S before 2025. +

Since May 6th, 2023, User Management API supports OAuth Server-to-Server (S2S) workflows; The JWT one is deprecated and will stop working from the 27th of January 2025. Existing integrations based on this authorization scheme will continue to work as usual until this date. Please migrate your project to use OAuth S2S before 2025.

For User Sync Tool users, please wait for the v2.9.0 release before migrating to OAuth Server-to-Server.

On August 8th, 2022, Document Cloud product names will remove the "DC" suffix. For example, "Acrobat Pro DC" will be renamed “Acrobat Pro".