User Management

User Management Endpoint Reference

Marketo provides a set of User Management endpoints allow you to perform CRUD operations on user records in Marketo.  Users are created by sending an invitation to a user, who then sets a password and gains access to Marketo for the first time.

Unlike other Marketo REST APIs, when using the User Management APIs:

  • You must use the HTTP header method to send the access token to authenticate.  You cannot pass access token as a query string parameter.  More information on authentication is here.
  • You must select a role permission from two different groups when creating the user role for Custom Service for REST API:
    1. “Access Users” permission from the Access Admin group
    2. “Access User Management Api” from the Access API group
  • Response bodies do not contain the “success” boolean attribute indicating success or failure of a call.  Instead you must evaluate the HTTP response status code.  If a call succeeds, a 200 OK is returned.  If a call fails, a non-200 level status code is returned and the response body contains the standard “errors” array with error code and descriptive error message.
  • The format of datetime strings is “yyyyMMdd’T’HH:mm:ss.SSS’t’+|-hhmm“.  This applies to the following attributes: createdAt, updatedAt, expiresAt.
  • User Management API endpoints are not prefixed with “/rest” like other endpoints.

 

Query

Query support for user management includes ability to retrieve all users, roles, and workspaces.  Additionally, you can retrieve a single user record by user id, or role/wordspace record by user id.

User by Id

The Get User by Id endpoint takes a single userid path parameter and returns a single user record for a user that has accepted their invitation.

Invited User by Id

The Get Invited User by Id endpoint takes a single userid path parameter and returns a single user record for a “pending” user (has not yet accepted their invitation).

Roles and Workspaces by Id

The Get Roles and Workspaces by Id endpoint takes a single userid path parameter and returns a list of user role and workspace records.  The response contains an array with one object that contains role and workspace id and name for the specified user.

Browse Users

The Get Users endpoint returns a list of all user records.  The optional pageSize parameter is an integer that specifies the maximum number of entries to return.  Default is 20.  Maximum is 200.  The optional pageOffset parameter is an integer that specifies where to begin retrieving entries.  Can be used in conjunction with pageSize.  Default is 0.

Browse Roles

The Get Roles endpoint returns a list of all role records.

Browse Workspaces

The Get Workspaces endpoint returns a list of all workspace records.

Invite User

The Invite User endpoint to sends a “Welcome to Marketo” email invitation to new user.  The email body contains a “Login to Marketo” link which allows user to access Marketo for the first time.  To accept the invitation, the email recipient clicks the “Login to Marketo” link, creates their password, and gains access to Marketo.  Until the acceptance process is complete, the invitation is “pending” and the user record may not be edited.  A pending invitation expires 7 days after being sent.  More information about managing users can be found here.

Parameters are passed in the request body in application/json format .

The following parameters are required:  emailAddress, firstName, lastName, userRoleWorkspaces.  The userRoleWorkspaces parameter is an array of objects which contain accessRoleId and workspaceId attributes.

The userid parameter is a unique user identifier string value used for user login purposes and must be formatted as an email address.  If not provided in the request, the value of userid will default to the value provided in emailAddress parameter.

The boolean apiOnly parameter specifies whether the user is an API-Only user.  The expiresAt parameter specifies when user login expires and is formatted using W3C ISO-8601 format (without milliseconds).  If not provided in request, the user never expires.  The reason parameter is a string that describes the reason for the user invitation.

The endpoint returns a value of “true” if successful, otherwise an error message is returned.

Below is an example of the “Welcome to Marketo” email invitation that is sent to the new user.  The email subject line is “Marketo Login Information”, the sender is the email address of the API-Only User associated with the REST API Custom Service, and the recipient is as specified via the firstName, lastName, and emailAddress parameters.

 

Below is an example of the “Create Password” prompt that appears after user clicks “Login to Marketo” link:

 

The user accepts the email invitation by entering her password twice and clicking on “CREATE PASSWORD” button.  She then is granted access to Marketo for the first time.

Update User

Update support for users includes ability to update user attributes or delete a user.  Only users that have accepted their invitation can be updated.  Attributes are passed as parameters the request body in application/json format .

Update User Attributes

The Update User Attributes endpoint takes a single userid path parameter and returns a single user record.  The request body contains one or more user attributes to update: emailAddress, firstName, lastName, expiresAt.

Delete User

The Delete User endpoint takes a single userid path parameter and deletes the corresponding user from the instance.  Note that this is a destructive delete and cannot be reversed.  If successful, a 200 OK is returned, otherwise an error message is returned.

Delete Invited User

The Delete Invited User endpoint takes a single userid path parameter and deletes the corresponding “pending” user from the instance (user had not yet accepted their invitation).  Note that this is a destructive delete and cannot be reversed.  If successful, a 200 OK is returned, otherwise an error message is returned.

Update Roles

Update support for roles includes ability to add and delete roles.  Attributes are passed as parameters the request body in application/json format.

Add Roles

The Add Roles endpoint takes a single userid path parameter and adds one or more user roles to the corresponding user.  The request body contains a list of one or more objects each containing an  accessRoleId and a workspaceId attribute.  If successful, the entire list of accessRoleId/workspaceId pairs for the specified user are returned.

Delete Roles

The Delete Roles endpoint takes a single userid path parameter and deletes one or more user roles from the corresponding user.  The request body contains a list of one or more objects each containing an  accessRoleId and a workspaceId attribute.  If successful, the remaining list of accessRoleId/workspaceId pairs for the specified user are returned.