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.


GET /v2/usermanagement/{orgId}/users

Retrieve a paged list of all users in your organization along with information about them. The number of users returned in each call is subject to change, currently the limit is max 400 entries/page. You can make multiple paginated calls to retrieve the full list of users.

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

Parameters

Name Type Req? Description
orgId path true The unique identifier for an organization. This is a string of the form A495E53@AdobeOrg where the prefix before the @ is a hexadecimal number. You can find this value as part of the URL path for the organization in the Admin Console or in the adobe.io console for your User Management integration.
X-Api-Key header true The API key specified in the Adobe IO Console for the UMAPI integration used to authorize this session. See the Getting Started documentation for details. The header name is X-Api-Key and this parameter is its value.
Authorization header true The OAuth token generated by the authorization server from the JWT exchange which starts every UMAPI session. (This token usually begins with the letters ‘ey’.) The header name is Authorization, and this parameter, preceded by the word ‘Bearer’ and a space, is its value, as in Authorization: Bearer ey....
page query false The page number being requested. Page numbers greater than what exist will return the last page of users. The page size is variable with the current value returned in the X-Page-Size response header.
content-type header false Used to specify the content type of the request data. Must be application/json
X-Request-Id header false An arbitrary string used to identify the corresponding response to a request. If a header with this name is provided in the request, the exact same header will be included in the response to that request.
directOnly query false 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.

Responses

Content-Type: application/json

200 OK

The response body contains a list of users in JSON format including the email, firstName and lastName. Please note that fields can be missing if there are no values, i.e. if the user is not a member of any groups then groups will not be returned. Use the response headers X-Total-Count and X-Page-Count to determine total number of users and total page count.

Headers

Header Description
X-Total-Count The total count of users being returned across all pages.
X-Page-Count The maximum number of pages that could be fetched with the criteria specified.
X-Current-Page The integer value of the page being returned.
X-Page-Size The number of entries in the page being returned.

All of the values for the listed headers are strings.

Examples

Response returning three users with different group membership and administrative rights:

[
    {
        "id": "4EB5B571575A6B057F000101@example.com",
        "email": "john@example.com",
        "status": "active",
        "groups": [
            "Marketing Cloud 1 - Default Access",
            "Marketing Cloud 1 - All Report Access",
            "Marketing Cloud 1 - EDITOR",
            "Marketing Cloud 1 - Default Access"
        ],
        "username": "john@example.com",
        "domain": "example.com",
        "firstName": "John",
        "lastName": "Doe",
        "countryCode": "US",
        "userType": "enterpriseID"
    },
    {
        "id": "6237573D58A4C1B90A494038@umsdkneworg1-t2example.com",
        "email": "jane@example.com",
        "status": "active",
        "username": "jane@example.com",
        "domain": "example.com",
        "firstName": "Jane",
        "lastName": "Doe",
        "countryCode": "US",
        "userType": "enterpriseID"
    },
    {
        "id": "0A0E84765756CF537F000101@example.com",
        "email": "bob@example.com",
        "status": "active",
        "groups": [
            "Document Cloud 1"
        ],
        "username": "bob@example.com",
        "domain": "example.com",
        "firstName": "Bob",
        "lastName": "James",
        "countryCode": "US",
        "userType": "enterpriseID"
    }
]

Schema Properties

user:
Represents a User object. Properties that are not populated will not be returned in the response. Some properties are not applicable for particular account types. See Identity Types for more information on account types.

  • adminRoles: string[]; The list of groups or roles that the user holds an administrative role. Possible roles include:
  • countryCode: string; A valid ISO 2-character country code.
  • domain: string; The user’s domain.
  • email: string
  • firstName: string
  • groups: string[]; The list of groups that the user is a current member of including user-groups and product profiles.
  • id: string
  • lastName: string
  • phoneNumber: string
  • 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.
  • userType: string, possible values: { "adobeID", "enterpriseID", "federatedID", "unknown" }; The user type. See Identity Types for more information.
  • username: string; The user’s username (applicable for Enterprise and Federated users). For most AdobeID users, this value will be the same as the email address.

Schema Model

[
  {
    "adminRoles": [
      "string"
    ],
    "countryCode": "string",
    "domain": "string",
    "email": "string",
    "firstName": "string",
    "groups": [
      "string"
    ],
    "id": "string",
    "lastName": "string",
    "phoneNumber": "string",
    "status": "string",
    "userType": "string",
    "username": "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

Example Requests

Retrieve the first page of users:

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

Retrieve the fourth page of users and their direct only memberships:

curl -X GET https://usermanagement.adobe.io/v2/usermanagement/12345@AdobeOrg/users?page=4&directOnly=true \
  --header 'Authorization: Bearer ey...' \
  --header 'X-Api-Key: 88ce03094fe74f4d91c2538217d007fe'

Throttling

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 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.