User Management Action Commands

The JSON commands structure contained in your POST request to the action endpoint specifies a sequence of commands. Each command entry specifies a user or a user group and a sequence of steps to be performed for that user or user group.

For a given command entry, the API attempts to perform the steps in the order that they appear. However, the order of execution of commands is not always guaranteed. If the same user or user group is listed in more than one command, results could differ depending on the order of command execution. Use the following order as guidance:

Command entries

Each command entry begins with a root command that specifies whether a set of actions applies to an individual user, or to a user group. The JSON commands structure allows a maximum of 10 users or user groups to be operated on per request.

Root commands

user: string The user field is an email address with a UID and domain component jdoe@example.com. Identity Types explains the different account types available.

usergroup: string To create, update or delete a user group, specify createUserGroup, deleteUserGroup, and updateUserGroup actions in the do list for the usergroup. To update the membership list specify add and remove actions in the do list for the usergroup. See User Group Action Commands for details.

do: Each root command has a single do entry. Within a command’s do entry, a set of step actions specify what management operations to perform for the root user or user group.

Step actions for users

This section describes step actions that can be performed for a user. For steps that can be performed for a user group, see User Group Action Commands.

The following properties apply to a user:

requestID: string Arbitrary string to be returned in the response payload. This is to help identify the response that corresponds to a particular command entry.

domain: string Federated IDs that are not email addresses, must supply the domain the user belongs to in order to identify the user. This is required for all operations; create, update, add, remove, and removeFromOrg. The domain field must be at the same level as the user field. The domain field is ignored if the user has an Adobe or Enterprise ID. Identity Types explains the different account types available.

useAdobeID: boolean When true, the user ID is interpreted to refer to an existing Adobe ID even if a Enterprise or Federated ID exists with the same name.

do: Lists the series of steps to complete for this command entry. For a single user command entry, there can be only one create user operation (createEnterpriseID, createFederatedID or addAdobeID) and one delete user operation (removeFromOrg).

addAdobeID:

Adds a user who has an existing Adobe ID. User-information fields such as firstname and lastname can be included.

Previously, when an Adobe ID user was added, the user would receive an email inviting them to join the organization.

See user-information for individual field descriptions.

{
  "addAdobeID": {
    "email": "string",
    "country": "string",
    "firstname": "string",
    "lastname": "string",
    "option": "string"
  }        
}

Usage:

[{
  "user" : "jdoe@domain1.com",
  "requestID": "action_1",
  "do" : [{
    "addAdobeID": {
      "email": "jdoe@domain1.com",
      "country": "US",
      "firstname": "John",
      "lastname": "Doe",
      "option": "ignoreIfAlreadyExists"
    }
  }]
}]

createEnterpriseID:

Creates an Enterprise ID. See user-information for individual field descriptions.

{
  "createEnterpriseID": {  
    "email": "string",
    "country": "string",
    "firstname": "string",
    "lastname": "string",
    "option": "string"
  }
}

Usage:

[{
  "user" : "jdoe@claimed-domain1.com",
  "requestID": "action_1",
  "do" : [{
    "createEnterpriseID": {
      "email": "jdoe@dclaimed-domain1.com",
      "country": "US",
      "firstname": "John",
      "lastname": "Doe",
      "option": "ignoreIfAlreadyExists"
    }
  }]
}]

createFederatedID:

Creates a Federated ID. See user-information for individual field descriptions.

{
  "createFederatedID": {
    "email": "string",
    "country": "string",
    "firstname": "string",
    "lastname": "string",
    "option": "string"
  }
}

Sample POST body for email based login:

[{
  "user" : "jdoe@claimed-domain1.com",
  "requestID": "action_1",
  "do" : [{
    "createFederatedID": {
      "email": "jdoe@claimed-domain1.com",
      "country": "US",
      "firstname": "John",
      "lastname": "Doe",
      "option": "ignoreIfAlreadyExists"
    }
  }]
}]

Sample POST body defining the domain:

[{
  "user" : "jdoe",
  "domain": "claimed-domain1.com",
  "requestID": "action_1",
  "do" : [{
    "createFederatedID": {
      "email": "jdoe@claimed-domain1.com",
      "country": "US",
      "firstname": "John",
      "lastname": "Doe",
      "option": "ignoreIfAlreadyExists"
    }
  }]
}]

User Information Fields

  • firstname: string; Limited to 250 characters. Required for createEnterpriseID and createFederatedID. Optional for addAdobeID.
  • lastname: string; Limited to 250 characters. Required for createEnterpriseID and createFederatedID. Optional for addAdobeID.
  • email: string; A valid email address. Required for createEnterpriseID, addAdobeID and createFederatedID. Limited to 60 characters.
  • country: string; A valid ISO 2 upper-case characters country code. Optional for createEnterpriseID and addAdobeID. Required for createFederatedID. The country value cannot be updated after it is set.
  • option: string, possible values: {ignoreIfAlreadyExists, updateIfAlreadyExists}; In addition to the new user’s field values, the parameters can include an option flag that specifies how to perform the create operation when a user with the given ID already exists in the user database. Default behaviour, when this option parameter is not provided, is to return an error. Optional property for createEnterpriseID, createFederatedID, addAdobeID. It only affects first name and last name metadata.
    • ignoreIfAlreadyExists: If the ID already exists, ignore the create step but process any other steps in the command entry for this user.
    • updateIfAlreadyExists: If the ID already exists, perform an update action using the parameters in the create step. After updating all fields present in the step, process any other steps in the command entry for this user.

update:

The update action writes new personal information to the user’s account details. You can update Enterprise and Federated IDs that are managed by your organization.

  • Independent Adobe IDs are managed by the individual user and cannot be updated through the User Management API. Attempting to update information for a user who has an Adobe ID will result in an error: error.update.adobeid.no.
  • For Federated IDs, the update request can only change the information that is stored by Adobe. You cannot use the User Management API to change information your organization stores outside of Adobe.
  • Identity Types explains the different account types available. See user-information for individual field descriptions.

The parameters of an update step specify the changed fields and their new values. If you do not specify a field, its value remains unchanged.

Inside update parameters that need an update should appear.

{
  "update": {
    "email": "string",
    "firstname": "string",
    "lastname": "string",
    "username": "string"
  }
}

Note: country is not updatable via UMAPI

Samples for update use-case scenarios with email based login:

  • Updating user’s Email and Last Name metadata but keeping the domain part constant 
    [{
"user": "jdoe@claimed-domain1.com",
"requestID": "action_1",
"do": [{
  "update": {
    "email": "jnew@claimed-domain1.com",
    "lastname": "new"
  }
}]
}]
  • Updating user’s Email metadata but also change the domain part

    Requirement: used domains should be claimed and added to same Admin Console Directory

    [{
"user": "jdoe@claimed-domain1.com",
"requestID": "action_1",
"do": [{
  "update": {
    "email": "jdoe@claimed-domain2.com"
  }
}]
}]
  • Updating user’s Username metadata but use a different domain than the Email for it

    Requirement: used domains should be claimed and added to same Admin Console Directory

    [{
"user": "jdoe@claimed-domain1.com",
"requestID": "action_1",
"do": [{
  "update": {
    "username": "jdoe@claimed-domain2.com"
  }
}]
}]
  • Updating user’s Username and Email metadata using new different domains for each

    Requirement: used domains should be claimed and added to same Admin Console Directory

    [{
"user": "jdoe@claimed-domain1.com",
"requestID": "action_1",
"do": [{
  "update": {
    "email": "canBeNew@claimed-domain2.com",
    "username": "canBeOther@claimed-domain3.com",
  }
}]
}]

Updating Email Policy

For all account types, the email address is used as a case-sensitive unique identifier. You cannot use the update request to change the letter case of the email address, once it has been set. There is an additional username field: for Adobe IDs and Enterprise IDs, the username is always the same as the email address, and the same is true by default for Federated IDs.

For Federated IDs, you can update the username field for users whose email address is in your domain. The username value can also be an email address, but you can never use it to identify a user in requests.

In case of email based login, if you use an update command to change a user’s Email metadata, the Username metadata is automatically updated to match, provided that all domains being used in the request are claimed.

[{
  "user": "jdoe@claimed-domain1.com",
    "do": [{
      "update": {
        "email": "jdoe@claimed-domain2.com"
      }
    }]
}]

After the above change, user’s Username and Email values in Admin Console will be equal to jdoe@claimed-domain2.com

add:

Adds a user as a member of a group. You can add a maximum of 10 memberships in one command entry. See Add/Remove Attributes section for full details of the group attribute.

{
  "add": {
    "group": [
      "group_name"
    ]
  }
}

Sample JSON body for email based login:

[{
  "user": "jdoe@claimed-domain1.com",
  "requestID": "action_1",
  "do": [{
    "add": {
      "group": [ 
        "group_name1", 
        "group_name2"
      ]
    }
  }]
}]

remove:

Removes the membership of users from groups. You can remove a maximum of 10 memberships in one command entry, unless you use the special “all” parameter to remove all memberships for the user. See Add/Remove attributes section for full details of the group attribute.

{
  "remove" : {
    "group": [
      "group_name"
    ]
  }
}

Additionally you can pass the attribute all to remove the user from all groups including product profiles, user-groups, and administrative groups (admin roles):

{
  "remove" : "all"
}

Sample JSON body for email based login:

  • removing a user’s membership from 2 groups 
    [{
"user": "jdoe@claimed-domain1.com",
"requestID": "action_1",
"do": [{
  "remove": {
    "group": [ 
      "group_name1", 
      "group_name2"
    ]
  }
}]
}]
  • remove the user account from all Groups/PLCs/Admin roles in Admin Console
  • org_admin (System Admin) role can’t be removed via UM API 
    [{
"user": "jdoe@claimed-domain1.com",
"requestID": "action_1",
"do": [{
  "remove": "all"
}]
}]

Add/Remove Attributes

The following attribute is available in both the add and remove operations for a user:

Add or remove membership in user groups and product profiles to control entitlements. Product profiles correspond to specific product access rights, so adding product access for a user is the same as adding that user to the corresponding product profile.

Add or remove membership in administrative groups to control administrative rights. There are three groups with fixed names corresponding to administrative roles:

  • Administrators: _org_admin
  • 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.

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.
  • An administrative group for a product profile or user group is named with the prefix _admin_ and the product-profile or user-group name. For example, _admin_MarketingProfile or _admin_PhotoshopUserGroup.
  • A developer group for a product profile is named with the prefix _developer_ and the product-profile name. For example _developer_MarketingProfile.

Use the group resource to retrieve information about defined groups.

removeFromOrg:

Removes the user’s membership in the organization, and optionally from membership in a domain that is linked to the given organization through the trusted-domain relationship. This includes any product configs and user-groups in the organization that they are a member of. There can only be a single removeFromOrg action in a command entry. If present, the removal action will be the last step invoked. If the user is specified by email address, then the domain of the email address specifies the domain of the account.

Note that the response always reports a successful result for this action, even if the user did not exist.

{
  "removeFromOrg": {
    "deleteAccount": boolean
  }
}
  • 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 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 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.

Sample JSON body for email based login:

[{
  "user": "jdoe@claimed-domain1.com",
  "requestID": "action_1",
  "do": [{
    "removeFromOrg": {
      "deleteAccount": false
    }
  }]
}]

User command request body schema for email based login scenario

[{
  "user": "string",
  "requestID": "string",
  "useAdobeID": boolean,
  "do": [
    {
      "addAdobeID": {
        "country": "string",
        "email": "string",
        "firstname": "string",
        "lastname": "string",
        "option": "string"
      }
    },
    {
      "createEnterpriseID": {
        "country": "string",
        "email": "string",
        "firstname": "string",
        "lastname": "string",
        "option": "string"
      }
    },
    {
      "createFederatedID": {
        "country": "string",
        "email": "string",
        "firstname": "string",
        "lastname": "string",
        "option": "string"
       }
    },
    {
      "add": {
        "group": [
          "string"
        ]
      }
    },
    {
      "remove": {
        "group": [
          "string"
        ]
      }
    },
    {
      "removeFromOrg": {
        "deleteAccount": boolean
      }
    },
    {
      "update": {
        "email": "string",
        "firstname": "string",
        "lastname": "string"
      }
    }
  ]
}]

Some other action examples

  • Mix of creating a Federated ID and add the user to the Product License Configurations Photoshop - 2Gb and Illustrator - 20Gb actions 
    [{
"user" : "jdoe@claimed-domain1.com",
"requestID" : "ed2148",
"do" : [
  {
    "createFederatedID": {
      "email": "jdoe@claimed-domain1.com",
      "country": "US",
      "firstname": "John",
      "lastname": "Doe"
    }
  },
  {
    "add" : {
      "group" : [ "Photoshop - 2Gb", "Illustrator - 20Gb"]
    }
  }
]
}]
  • Mix of creating a Federated ID and updating the username metadata actions: 
    [{
"user" : "jdoe@claimed-domain1.com",
"requestID" : "ed2149",
"do" : [
  {
    "createFederatedID": {
      "email": "jdoe@claimed-domain1.com",
      "country": "US",
      "firstname": "John",
      "lastname": "Doe"
    }
  },
  {
    "update" : {
      "username" : "jdoe@claimed-domain2.com"
    }
  }
]
}]
  • Add the Product Owner Admin role for a user: 
    [
{
  "user" : "jdoe@claimed-domain1.com",
  "do" : [{
      "add" : {
          "group" : ["_product_admin_myProduct1Name"]
      }
    }]
}
]
  • Remove the admin role for the user for a given product profile: 
    [
{
  "user": "jdoe@claimed-domain1.com",
  "do": [{
      "remove": {
        "group" : ["_admin_myProductProfile1Name"]
      }
  }]
}
]
  • Add the developer role for the user for a given product profile: 
    [{
  "user": "jdoe@claimed-domain1.com",
  "do": [{
      "add": {
        "group" : ["_developer_myProductProfile1Name"]
      }
  }]
}]