Get Users in a User Group or Product Profile

GET /v2/usermanagement/users/{orgId}/{page}/{groupName}

Gets a paged list of users in a specific group of an organization along with information about them. Groups can be named user groups, product profiles, or group-specific administrative groups.

For product profiles:

• Pass the directOnly flag to return only those users who have a direct membership in the product profile.
• Pass the status parameter to return only those users who have the “active” or “inactive” status in the product profile.

Throttle Limits: Maximum 25 requests per minute per a client. See Throttling Limits for full details.

• Parameters
• Responses
• Example Requests
• Throttling Limits

Parameters

Responses

Content-Type: application/json

• 200: OK
• 400: Bad Request
• 401: Unauthorized
• 403: Forbidden
• 429: Too Many Requests

Use only those properties that are documented in the Response Properties section. Additional fields can appear in the response, but should not be relied upon.

200 OK

A successful request returns a response body with the requested user data in JSON format. When the response contains the last paged entry, the response includes the field lastPage : true. If the returned page is not the last page, make additional paginated calls to retrieve the full list.

Identity Types explains the different account types available.

Headers

All of the values for the listed headers are strings.

Examples

Response returning three members of the Document Cloud 1 group, showing their various other group memberships:

{
    "lastPage": false,
    "result": "success",
    "groupName": "Document Cloud 1",
    "users": [
        {
            "email": "john@example.com",
            "status": "active",
            "groups": [
                "Document Cloud 1"
            ],
            "username": "john",
            "domain": "example.com",
            "country": "US",
            "type": "federatedID",
            "tags": [
                "edu_student"
            ]
        },
        {
            "email": "jane@example.com",
            "status": "active",
            "groups": [
                "Document Cloud 1",
                "Support for AEM Mobile",
                "_admin_Document Cloud 1",
                "_admin_Support for AEM Mobile",
                "_admin_Default Support profile",
                "_admin_Creative Cloud 1",
                "_deployment_admin",
                "_developer_Document Cloud 1"
            ],
            "username": "jane",
            "domain": "example.com",
            "country": "US",
            "type": "federatedID"
        },
        {
            "email": "bob@example.com",
            "status": "active",
            "groups": [
                "Document Cloud 1",
                "Creative Cloud 1"
            ],
            "username": "bob",
            "domain": "example.com",
            "country": "US",
            "type": "federatedID"
        }
        ...
      ]
}

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:

{
    "lastPage": false,
    "result": "success",
    "groupName": "Document Cloud 1",
    "users": [
        {
            "email": "john@example.com",
            "status": "active",
            "username": "john",
            "domain": "example.com",
            "country": "US",
            "type": "federatedID",
            "tags": [
                "edu_student"
            ]
        },
        {
            "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:

{
    "lastPage": true,
    "result": "success",
    "groupName": "Document Cloud 1",
    "users": [
        {
            "email": "jim@example.com",
            "status": "active",
            "groups": [
                "Document Cloud 1"
            ],
            "username": "jim",
            "domain": "example.com",
            "country": "US",
            "type": "adobeID"
        }
    ]
}

Response Properties

result: string, The status of the request. One of success or an error key: { "success", "error", "error.apikey.invalid", "error.user.email.invalid", "error.api.user.not.parent.org", "error.organization.invalid_id" }

message: string An error message, returned only if initial validation of the request fails. It is not populated when a 200 status is returned.

{
  "result": "error.organization.invalid_id",
  "message": "Bad organization Id"
}

users: Contains a list of User objects. Properties that are not populated are not returned in the response. Some properties are not applicable for particular account types.

• country: string; A valid ISO 2-character country code.
• domain: string; The user’s domain.
• email: string; The user’s email address.
• firstname: string; The user’s first name.
• groups: string[]; The list of groups in which the user is a current member, including, user groups, product profiles, product admin groups, and group-specific admin groups. Administrative groups are named with a prefix and the group name. For example, _product_admin_Photoshop, _admin_DesignTools, or _developer_Marketing. You should avoid any logic that expects fixed group names as these are liable to change without notice. Organization-wide admin groups are:
  • _org_admin: The user is a System Administrator.
  • _deployment_admin: The user is a Deployment Administrator.
  • _support_admin: The user is a Support Administator.
• id: string; The user’s unique identifier.
• lastname: string; The user’s last name.
• status: string; A user’s status with the organization. Only “active” users are returned by Get User Information and Get Users in Organization. One of the following:
  • “active”: Normal status for a user account in good standing.
  • “disabled”: Disabled temporarily - user is not allowed to login, but is not removed.
  • “locked”: Disabled permanently - user is not allowed to login, but is not removed.
  • “removed”: The user account is being removed.
• type: string, The user type, one of: { "adobeID", "enterpriseID", "federatedID", "unknown" }. See Identity Types for more information.
• username: string; The user’s username (applicable for Enterprise and Federated users). For most Adobe ID 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.

Schema Model

{
  "groupName": "string",
  "lastPage": boolean,
  "message": "string",
  "result": "string",
  "users": [
    {
      "country": "string",
      "domain": "string",
      "email": "string",
      "firstname": "string",
      "groups": [
        "string"
      ],
      "id": "string",
      "lastname": "string",
      "status": "string",
      "type": "string",
      "username": "string",
      "tags": [
          "string"
      ]
    }
  ]
}

400 Bad Request

Some parameters of the request were not understood by the server or the Service Account Integration certificate has expired.

401 Unauthorized

Possible causes are:

• Invalid or expired token.
• Invalid Organization.

< HTTP/1.1 401 Unauthorized
< Content-Type: */*
< Date: Thu, 22 Jun 2017 09:47:04 GMT
< WWW-Authenticate: Bearer realm="JIL", error="invalid_token", error_description="The access token is invalid"
< X-Request-Id: user-assigned-request-id
< Content-Length: 0
< Connection: keep-alive

403 Forbidden

Possible causes are:

• Missing API key.
• The organization is currently migrating. Either from DMA or to One Console.
• API key is not permitted access.

< HTTP/1.1 403 Forbidden
< Date: Thu, 22 Jun 2017 09:41:22 GMT
< X-Request-Id: user-assigned-request-id
< Content-Length: 0
< Connection: keep-alive

404 Not Found

The group was not found in the given organization.

< HTTP/1.1 404 Not Found
< Canonical-Resource: /v2/usermanagement/users/{orgId}/{page}/{groupName}
{"lastPage":false,"result":"error.group.not_found","message":"Not found: Group 1234"}

Example Requests

Retrieve the first page of users for group Photoshop:

curl -X GET https://usermanagement.adobe.io/v2/usermanagement/users/12345@AdobeOrg/0/photoshop \
  --header 'Authorization: Bearer ey...' \
  --header 'X-Api-Key: 88ce03094fe74f4d91c2538217d007fe'

Retrieve the fifth page of users for user group DevOps:

curl -X GET https://usermanagement.adobe.io/v2/usermanagement/users/12345@AdobeOrg/4/DevOps \
  --header 'Authorization: Bearer ey...' \
  --header 'X-Api-Key: 88ce03094fe74f4d91c2538217d007fe'

Retrieve a list of active users using the status parameter. This query will return all direct members that have an active license for Photoshop.

 curl -X GET https://usermanagement.adobe.io/v2/usermanagement/users/12345@AdobeOrg/0/photoshop?status=active \
  --header 'Authorization: Bearer ey...' \
  --header 'X-Api-Key: 88ce03094fe74f4d91c2538217d007fe'

Throttling Limits

To protect the availability of the Adobe back-end user identity systems, the User Management API imposes limits on client access to the data. Limits apply to the number of calls that an individual client can make within a time interval, and global limits apply to access by all clients within the time period. For this API the throttling limits are as follows:

• Maximum calls per client: 25 requests per a minute
• Maximum calls for the application: 100 requests per a minute

When the client or global access limit is reached, further calls fail with HTTP error status 429 Too Many Requests. The Retry-After header is included in the 429 response, and provides the minimum amount of time that the client should wait until retrying. See RFC 7231 for full information.

The User Management API recommends limiting your syncs to two hourly intervals and consider scheduling your sync for a time that works best for you, taking into account other timezones and clients. This will help to prevent how often your client is throttled.

The following sample shows a 429 response with the Retry-After header detailing the number of seconds to wait before retry:

========================= RESPONSE =========================
Status code: 429
-------------------------- header --------------------------
Content-Type: application/json
Date: Fri, 19 Jan 2018 10:31:43 GMT
Retry-After: 38
Server: APIP
X-Request-Id: iEUtsLiFgj3R4xsbirAyZlMyaxRTo8Xo
Content-Length: 54
Connection: keep-alive
--------------------------- body ---------------------------
{
  "error_code" : "429050",
  "message" : "Too many requests"
}
============================================================

Because of the global limits, and because the specific limits may change, you cannot simply limit the rate at which you make your own calls. You must handle rate-limit errors by retrying the failed calls. We recommend an exponential backoff retry technique for handling such errors.

Handling error responses

When you retry a failed request, the retry can also fail, and can fall back into the retry loop, adding to the system overload. The exponential backoff retry method increases the period between retries, so that the client makes fewer calls while the system is overloaded.

To implement an exponential backoff method, you increase the retry interval with each failed request. You should retry sending the request after a certain number of seconds, and increase that interval by a random amount with each attempt. For example, you can double the retry period each time, or escalate it by a power of 2, and then add a small random delay between failures.

A small random delay, known as “jitter,” prevents the “herd effect” that can occur if many clients attempt to reconnect to a recovering system at the same time. Without jitter, all of the retries could occur after 20 seconds, then 40 seconds, and so on. With the jitter, different retries occur at slightly different intervals. This allows the system to recover without further overloading it.

For an example of how to implement this error-handling method, see “Retrying Requests” in the User Management Walkthrough.