Access and manage user accounts

Overview

Moloco provides two different sets of APIs: the Campaign management API and the Auth API. The Campaign management API consists of a set of APIs you can use to manage campaign operations and analyses. To learn more about the Campaign management API, see Manage your campaign. The Auth API consists of a set of APIs you can use to manage operations related to your workplace, users, user roles, and access token before using the Campaign management API.

Entities in the Auth API

The Auth API consists of the following entities: Workplace, User, and Role. The following diagram illustrates the relationship between these entities.

Workplace

A Workplace entity represents the workplace a user account is assigned to. It includes the following properties.

Attribute	Type	Mandatory	Description
id	string	Y	The workplace ID.
title	string	Y	The workplace title.

User

A User entity represents a single user. You can register a user to one or more workplaces. A User entity includes the following properties.

Attribute	Type	Mandatory	Description
email	string	Y	The user’s Moloco account email address.
id	string	Y	The user’s Moloco-assigned ID.
name	string	Y	The user’s name.
signed_up	boolean	Y	This property indicates whether the user has signed up for a Moloco account. Valid values are `TRUE` and `FALSE`.
created_at	timestamp	Y	The date and time the user entity was created. e.g.,) `1957-06-09T13:43:21.054Z`
updated_at	timestamp	Y	The date and time the user entity was updated. e.g.,) `"1957-06-09T13:43:21.054Z"`

Role

A Role entity represents the administrative role you can assign to a user, and the API requests users can make are tied to their assigned roles. Role entities have a binding concept, meaning that a role is bound to a workplace or an ad account. Users can have multiple roles but in only those workplaces they are assigned to, and they can be assigned only one role per ad account or workplace. When a user has multiple roles, their scope of authority is governed by the role with the most authority. For example, a user who is a workplace owner in Workplace A can make an API request to invite another user to Workplace A but can't do the same for Workplace B. If this user is also an ad account owner in Ad account A, which is under Workplace A, the user has the authority of a workplace owner in Workplace A. As an ad account owner, this user can't be assigned other roles such as ad account member or viewer because they can be assigned only one role per ad account or workplace. To learn more about role binding, see Google Cloud's IAM.

You can specify one of the following values for the type property of the role object. They represent the roles you can assign to a user. For more information, see the API reference.

Role	Description
WORKPLACE_OWNER	Workplace owner. A workplace owner has full authority to perform any available workplace operation, and make changes to any of the entities in the workplace.
AD_ACCOUNT_OWNER	Ad account owner. An ad account owner has full authority to perform any available ad account operation, and make changes to any of the entities in the ad account, including the ad account itself.
AD_ACCOUNT_MEMBER	Ad account member. An ad account member can invite other users as ad account members or viewers, and can create and update campaigns under the ad account. Ad account members can view the profile of all users in the ad account, and they can update their own information.
AD_ACCOUNT_VIEWER	Ad account viewer. An ad account viewer has limited authority and is only able to view information about the campaigns under the ad account and associated reports.

Note: An AdAccount entity is included in the Campaign management API. See Manage your campaign for more information.

Grant and revoke user roles

The following table lists the roles a user with one of the available roles can assign to another user. To learn more about how to assign a role to another user, see Grant a role to a user.

Role	Roles this user can assign to another user
WORKPLACE_OWNER	WORKPLACE_OWNER AD_ACCOUNT_OWNER AD_ACCOUNT_MEMBER AD_ACCOUNT_VIEWER
AD_ACCOUNT_OWNER	AD_ACCOUNT_OWNER AD_ACCOUNT_MEMBER AD_ACCOUNT_VIEWER
AD_ACCOUNT_MEMBER	AD_ACCOUNT_MEMBER AD_ACCOUNT_VIEWER
AD_ACCOUNT_VIEWER	N/A

The following table lists the roles a user with one of the available roles can remove from another user. To learn more about how to un-assign a role from another user, see Revoke a role from a user.

Role	Roles this user can remove from another user
WORKPLACE_OWNER	WORKPLACE_OWNER AD_ACCOUNT_OWNER AD_ACCOUNT_MEMBER AD_ACCOUNT_VIEWER
AD_ACCOUNT_OWNER	AD_ACCOUNT_OWNER AD_ACCOUNT_MEMBER AD_ACCOUNT_VIEWER

Access token for authentication

You can use the Auth API to get and refresh an access token you need to be able to make API requests. To learn how to get an access token, see Issue a new token. To learn how to refresh an access token, see Refresh the token. For more information about the authentication process, see Get started with Moloco Ads API.

Note: Each workplace has its own access token. To make changes to entities in another workplace, you must get a new token for that workplace.