Administrative REST surface for managing Marketo Engage users, roles, workspaces and invitations — list all users, invite a user, read and assign roles, list workspaces, update user attributes, and delete users or pending invitations. 12 operations under /userservice/management/v1, published by Adobe as Swagger 2.0. This is the only Marketo surface whose specification declares real 401/403/404 responses.
{
"swagger": "2.0",
"info": {
"description": "Marketo Engage Rest API",
"version": "1.0",
"title": "Marketo Engage Rest API",
"termsOfService": "https://www.marketo.com/company/legal/",
"contact": {
"name": "Adobe Developer Relations",
"url": "https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/home",
"email": ""
},
"license": {
"name": "API License Agreement",
"url": "https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/api-license"
}
},
"host": "localhost:8080",
"basePath": "/",
"schemes": ["https"],
"tags": [
{
"name": "User Management",
"description": "Marketo Engage provides a set of User Management endpoints allow you to perform CRUD operations on user records in Marketo."
}
],
"paths": {
"/userservice/management/v1/users/allusers.json": {
"get": {
"tags": [
"User Management"
],
"summary": "Get Users",
"description": "Retrieve a list of all user records. Required Permissions: Access User Management Api and Access Users",
"operationId": "getUsersUsingGET",
"produces": [
"application/json"
],
"parameters": [
{
"name": "pageOffset",
"in": "query",
"description": "Integer offset for paging. Default is 0",
"required": false,
"type": "integer",
"default": 0,
"format": "int32"
},
{
"name": "pageSize",
"in": "query",
"description": "Maximum number of users to return. Max 200, default 20",
"required": false,
"type": "integer",
"default": 20,
"format": "int32"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/ResponseOfAllUsers"
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
},
"deprecated": false
}
},
"/userservice/management/v1/users/invite.json": {
"post": {
"tags": [
"User Management"
],
"summary": "Invite User",
"description": "Send an email invitation to new user. Required Permissions: Access User Management Api and Access Users",
"operationId": "inviteUserUsingPOST",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"in": "body",
"name": "inviteUserRequest",
"description": "inviteUserRequest",
"required": true,
"schema": {
"$ref": "#/definitions/InviteUserRequest"
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "string"
}
},
"201": {
"description": "Created"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
},
"deprecated": false
}
},
"/userservice/management/v1/users/roles.json": {
"get": {
"tags": [
"User Management"
],
"summary": "Get Roles",
"description": "Retrieve list of all role records. Required Permissions: Access User Management Api and Access Users",
"operationId": "getRolesUsingGET",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/ResponseOfRole"
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
},
"deprecated": false
}
},
"/userservice/management/v1/users/workspaces.json": {
"get": {
"tags": [
"User Management"
],
"summary": "Get Workspaces",
"description": "Retrieve list of workspace records. Required Permissions: Access User Management Api and Access Users",
"operationId": "getWorkspacesUsingGET",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/ResponseOfWorkspace"
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
},
"deprecated": false
}
},
"/userservice/management/v1/users/{userid}/delete.json": {
"post": {
"tags": [
"User Management"
],
"summary": "Delete User",
"description": "Delete user. Required Permissions: Access User Management Api and Access Users",
"operationId": "deleteUserUsingPOST",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "userid",
"in": "path",
"description": "User id in the form of an email address",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
},
"deprecated": false
}
},
"/userservice/management/v1/users/{userid}/invite/delete.json": {
"post": {
"tags": [
"User Management"
],
"summary": "Delete Invited User",
"description": "Delete pending user. A pending user is a user that has not yet accepted invitation. Required Permissions: Access User Management Api and Access Users",
"operationId": "deleteInvitedUserUsingPOST",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "userid",
"in": "path",
"description": "User id in the form of an email address",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
},
"deprecated": false
}
},
"/userservice/management/v1/users/{userid}/update.json": {
"post": {
"tags": [
"User Management"
],
"summary": "Update User Attributes",
"description": "Update one or more user attributes. Required Permissions: Access User Management Api and Access Users",
"operationId": "updateUserAttributeUsingPOST",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"in": "body",
"name": "updateUserAttributesRequest",
"description": "updateUserAttributesRequest",
"required": true,
"schema": {
"$ref": "#/definitions/UpdateUserAttributesRequest"
}
},
{
"name": "userid",
"in": "path",
"description": "User id in the form of an email address",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/ResponseOfUser"
}
},
"201": {
"description": "Created"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
},
"deprecated": false
}
},
"/userservice/management/v1/users/{userid}/roles.json": {
"get": {
"tags": [
"User Management"
],
"summary": "Get Roles and Workspaces by Id",
"description": "Get roles and workspaces for a given user. Required Permissions: Access User Management Api and Access Users",
"operationId": "getUserRolesAndWorkspacesUsingGET",
"produces": [
"application/json"
],
"parameters": [
{
"name": "userid",
"in": "path",
"description": "User id in the form of an email address",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/UserRoleWorkspace"
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
},
"deprecated": false
}
},
"/userservice/management/v1/users/{userid}/roles/create.json": {
"post": {
"tags": [
"User Management"
],
"summary": "Add Roles",
"description": "Add roles to a user. Required Permissions: Access User Management Api and Access Users",
"operationId": "addRolesUsingPOST",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"in": "body",
"name": "addRolesRequest",
"description": "addRolesRequest",
"required": true,
"schema": {
"$ref": "#/definitions/AddRolesRequest"
}
},
{
"name": "userid",
"in": "path",
"description": "User id in the form of an email address",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/UserRoleWorkspace"
}
}
},
"201": {
"description": "Created"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
},
"deprecated": false
}
},
"/userservice/management/v1/users/{userid}/roles/delete.json": {
"post": {
"tags": [
"User Management"
],
"summary": "Delete Roles",
"description": "Delete roles from user. Required Permissions: Access User Management Api and Access Users",
"operationId": "deleteRolesUsingPOST",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"in": "body",
"name": "deleteRolesRequest",
"description": "deleteRolesRequest",
"required": true,
"schema": {
"$ref": "#/definitions/DeleteRolesRequest"
}
},
{
"name": "userid",
"in": "path",
"description": "User id in the form of an email address",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/UserRoleWorkspace"
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
},
"deprecated": false
}
},
"/userservice/management/v1/users/{userid}/user.json": {
"get": {
"tags": [
"User Management"
],
"summary": "Get User by Id",
"description": "Retrieve a single user record through its Id. Required Permissions: Access User Management Api and Access Users",
"operationId": "getUserUsingGET",
"produces": [
"application/json"
],
"parameters": [
{
"name": "userid",
"in": "path",
"description": "User id in the form of an email address",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/ResponseOfUser"
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
},
"deprecated": false
}
},
"/userservice/management/v1/users/{userid}/invite.json": {
"get": {
"tags": [
"User Management"
],
"summary": "Get Invited User by Id",
"description": "Retrieve a single pending user record through its Id. A pending user is a user that has not yet accepted invitation. Required Permissions: Access User Management Api and Access Users",
"operationId": "getInvitedUserUsingGET",
"produces": [
"application/json"
],
"parameters": [
{
"name": "userid",
"in": "path",
"description": "User id in the form of an email address",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/ResponseOfInvitedUser"
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
},
"deprecated": false
}
}
},
"definitions": {
"ResponseOfRole": {
"type": "object",
"required": [
"description",
"id",
"isHidden",
"isOnlyAllZones",
"name",
"createdAt",
"updatedAt",
"type"
],
"properties": {
"errors": {
"type": "array",
"description": "Array of errors that occurred if the request was unsuccessful",
"items": {
"$ref": "#/definitions/Error"
}
},
"description": {
"type": "string",
"description": "Role description"
},
"id": {
"type": "integer",
"description": "Role id",
"format": "int32"
},
"isHidden": {
"type": "boolean",
"description": "Whether role is hidden"
},
"isOnlyAllZones": {
"type": "boolean",
"description": "Whether role is all zones"
},
"name": {
"type": "string",
"description": "Role name"
},
"createdAt": {
"type": "string",
"description": "Role creation time"
},
"updatedAt": {
"type": "string",
"description": "Role update time"
},
"type": {
"type": "string",
"description": "Role type"
}
},
"title": "ResponseOfRole"
},
"ResponseOfWorkspace": {
"type": "object",
"required": [
"currencyInfo",
"description",
"globalViz",
"id",
"name",
"status"
],
"properties": {
"errors": {
"type": "array",
"description": "Array of errors that occurred if the request was unsuccessful",
"items": {
"$ref": "#/definitions/Error"
}
},
"currencyInfo": {
"type": "string",
"description": "Workspace currency information"
},
"description": {
"type": "string",
"description": "Workspace description"
},
"globalViz": {
"type": "integer",
"description": "Workspace global visualization",
"format": "int32"
},
"id": {
"type": "integer",
"description": "Workspace id",
"format": "int32"
},
"name": {
"type": "string",
"description": "Workspace name"
},
"createdAt": {
"type": "string",
"description": "Workspace creation time"
},
"updatedAt": {
"type": "string",
"description": "Workspace updated time"
},
"status": {
"type": "string",
"description": "Workspace status"
}
},
"title": "ResponseOfWorkspace"
},
"AddRolesRequest": {
"type": "object",
"required": [
"input"
],
"properties": {
"input": {
"type": "array",
"description": "List of roles to add",
"items": {
"$ref": "#/definitions/UserRoleWorkspaceId"
}
}
}
},
"DeleteRolesRequest": {
"type": "object",
"required": [
"input"
],
"properties": {
"input": {
"type": "array",
"description": "List of roles to delete",
"items": {
"$ref": "#/definitions/UserRoleWorkspaceId"
}
}
}
},
"UpdateUserAttributesRequest": {
"type": "object",
"properties": {
"apiOnly": {
"type": "boolean",
"description": "Whether the user is API-Only. Default is false"
},
"emailAddress": {
"type": "string",
"description": "User email address",
"minLength": 1,
"maxLength": 2147483647,
"pattern": "^(\"?)(?:[^\"])(?:[-\\w.!#$%&\\'*+\\/=?^_`{|}~])*\\1@(\\w[-\\w]{0,62}\\.)+[A-Za-z]{2,63}$"
},
"expiresAt": {
"type": "string",
"description": "Date and time when user login expires. Example: yyyy-MM-dd'T'HH:mm:ss.SSS't'Z",
"example": "yyyyMMdd'T'HH:mm:ss'.'S't'Z"
},
"firstName": {
"type": "string",
"description": "User first name"
},
"lastName": {
"type": "string",
"description": "User last name"
}
},
"title": "UpdateUserAttributesRequest"
},
"InviteUserRequest": {
"type": "object",
"required": [
"emailAddress",
"firstName",
"lastName",
"userRoleWorkspaces"
],
"properties": {
"apiOnly": {
"type": "boolean",
"description": "Whether the user is API-Only. Default is false"
},
"emailAddress": {
"type": "string",
"description": "User email address",
"minLength": 1,
"maxLength": 2147483647,
"pattern": "^(\"?)(?:[^\"])(?:[-\\w.!#$%&\\'*+\\/=?^_`{|}~])*\\1@(\\w[-\\w]{0,62}\\.)+[A-Za-z]{2,63}$"
},
"expiresAt": {
"type": "string",
"description": "Date and time when user login expires. Must be valid ISO-8601 string. See <a href=\"http://developers.marketo.com/rest-api/lead-database/fields/field-types/\">Datetime</a> field type description."
},
"firstName": {
"type": "string",
"description": "User first name"
},
"lastName": {
"type": "string",
"description": "User last name"
},
"userid": {
"type": "string",
"description": "Marketo Identity users should use an email address. Adobe Identity users should use the generated GUID."
},
"reason": {
"type": "string",
"description": "Reason for user invitation"
},
"userRoleWorkspaces": {
"type": "array",
"items": {
"$ref": "#/definitions/UserRoleWorkspaceId"
}
}
},
"title": "InviteUserRequest"
},
"ResponseOfUser": {
"type": "object",
"required": [
"userid",
"firstName",
"lastName",
"emailAddress",
"optedIn",
"failedLogins",
"failedDeviceCode",
"isLocked",
"lockedReason",
"id",
"apiOnly",
"userRoleWorkspaces",
"expiresAt",
"lastLoginAt"
],
"properties": {
"errors": {
"type": "array",
"description": "Array of errors that occurred if the request was unsuccessful",
"items": {
"$ref": "#/definitions/Error"
}
},
"apiOnly": {
"type": "boolean",
"description": "Whether the user is API-Only"
},
"emailAddress": {
"type": "string",
"description": "User email address"
},
"expiresAt": {
"type": "string",
"description": "Date and time when user login expires. Example: yyyy-MM-dd'T'HH:mm:ss.SSS't'Z",
"example": "yyyy-MM-dd'T'HH:mm:ss.SSS't'Z"
},
"lastLoginAt": {
"type": "string",
"description": "Date and time of user's most recent login. Example: yyyy-MM-dd'T'HH:mm:ss.SSS't'Z",
"example": "yyyy-MM-dd'T'HH:mm:ss.SSS't'Z"
},
"failedDeviceCode": {
"type": "integer",
"description": "Device code for user login failure",
"format": "int32"
},
"failedLogins": {
"type": "integer",
"description": "Count of user login failures",
"format": "int32"
},
"firstName": {
"type": "string",
"description": "User first name"
},
"id": {
"type": "integer",
"description": "User identifier",
"format": "int32"
},
"isLocked": {
"type": "boolean",
"description": "Whether user account is locked"
},
"lastName": {
"type": "string",
"description": "User last name"
},
"lockedReason": {
"type": "string",
"description": "Reason that user account is locked"
},
"optedIn": {
"type": "boolean",
"description": "Whether user has opted in"
},
"userRoleWorkspaces": {
"type": "array",
"items": {
"$ref": "#/definitions/UserRoleWorkspace"
}
},
"userid": {
"type": "string",
"description": "Marketo Identity users should use an email address. Adobe Identity users should use the generated GUID."
}
},
"title": "ResponseOfUser"
},
"ResponseOfInvitedUser": {
"type": "object",
"required": [
"id",
"firstName",
"lastName",
"emailAddress",
"userid",
"subscriptionId",
"status",
"expiresAt",
"createdAt",
"updatedAt"
],
"properties": {
"errors": {
"type": "array",
"description": "Array of errors that occurred if the request was unsuccessful",
"items": {
"$ref": "#/definitions/Error"
}
},
"id": {
"type": "integer",
"description": "User identifier",
"format": "int32"
},
"firstName": {
"type": "string",
"description": "User first name"
},
"lastName": {
"type": "string",
"description": "User last name"
},
"emailAddress": {
"type": "string",
"description": "User email address"
},
"userid": {
"type": "string",
"description": "Marketo Identity users should use an email address. Adobe Identity users should use the generated GUID."
},
"subscriptionId": {
"type": "string",
"description": "Subscription ID"
},
"status": {
"type": "string",
"enum": [
"pending"
],
"description": "User status"
},
"expiresAt": {
"type": "string",
"description": "Date and time when user login expires. Example: yyyy-MM-dd'T'HH:mm:ss.SSS't'Z",
"example": "yyyy-MM-dd'T'HH:mm:ss.SSS't'Z"
},
"createdAt": {
"type": "string",
"description": "Date and time when user login was created. Example: yyyy-MM-dd'T'HH:mm:ss.SSS't'Z",
"example": "yyyy-MM-dd'T'HH:mm:ss.SSS't'Z"
},
"updatedAt": {
"type": "string",
"description": "Date and time when user login was last updated. Example: yyyy-MM-dd'T'HH:mm:ss.SSS't'Z",
"example": "yyyy-MM-dd'T'HH:mm:ss.SSS't'Z"
}
},
"title": "ResponseOfInvitedUser"
},
"ResponseOfAllUsers": {
"type": "object",
"required": [
"userid",
"firstName",
"lastName",
"emailAddress",
"id",
"apiOnly"
],
"properties": {
"errors": {
"type": "array",
"description": "Array of errors that occurred if the request was unsuccessful",
"items": {
"$ref": "#/definitions/Error"
}
},
"apiOnly": {
"type": "boolean",
"description": "Whether the user is API-Only"
},
"emailAddress": {
"type": "string",
"description": "User email address"
},
"firstName": {
"type": "string",
"description": "User first name"
},
"id": {
"type": "integer",
"description": "User identifier",
"format": "int32"
},
"lastName": {
"type": "string",
"description": "User last name"
},
"userid": {
"type": "string",
"description": "Marketo Identity users should use an email address. Adobe Identity users should use the generated GUID."
}
},
"title": "ResponseOfAllUsers"
},
"UserRoleWorkspace": {
"type": "object",
"required": [
"accessRoleId",
"workspaceId"
],
"properties": {
"accessRoleId": {
"type": "integer",
"description": "User role Id",
"format": "int32"
},
"accessRoleName": {
"type": "string",
"description": "User role description"
},
"workspaceId": {
"type": "integer",
"description": "User workspace Id",
"format": "int32"
},
"workspaceName": {
"type": "string",
"description": "User workspace name"
}
},
"title": "UserRoleWorkspace"
},
"UserRoleWorkspaceId": {
"type": "object",
"required": [
"accessRoleId",
"workspaceId"
],
"properties": {
"accessRoleId": {
"type": "integer",
"format": "int32",
"description": "User role id"
},
"workspaceId": {
"type": "integer",
"format": "int32",
"description": "User workspace id"
}
}
},
"Error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"format": "int32",
"description": "Integer error code of the error"
},
"message": {
"type": "string",
"description": "Message describing the cause of the Error"
}
}
}
}
}