Overview

MOLOCO Cloud Auth API provides the following auth functions that MOLOCO Cloud API users need in advance to use APIs such as campaign management API or report API.

  • Workplace, User and Role management
  • Token issuance for then authentication of API user

Entities

There are several entities which are related to auth.

Workplace

Workplace entity has an id and a title.

Attribute

Type

Mandatory

Description

id

string

Y

The workplace ID.

title

string

Y

The workplace title.

User

User entity represents a single user. About the signed_up field, it indicates whether the user has finished the sign up process.

Attribute

Type

Mandatory

Description

email

string

Y

The user’s email address.

id

string

Y

The user’s ID.

name

string

Y

The user’s name.

signed_up

boolean

Y

The state that indicates if the user has finished the sign up process.

created_at

timestamp

Y

The time when the user entity is created at.

updated_at

timestamp

Y

The time when the user entity is updated at.

Role

Role entities have a binding concept. Users can call the Auth API depending on their role. For example, the user who has a WORKPLACE_OWNER role bound to workplace A can invite another user to workplace A. The role is bound to a certain resource, in this case it’s Workplace id or AdAccount id. (Role binding concept is similar to that of Google Cloud's IAM)

Value

Description

WORKPLACE_OWNER

Workplace owner

AD_ACCOUNT_OWNER

AdAccount owner

AD_ACCOUNT_MEMBER

AdAccount member

AD_ACCOUNT_VIEWER

AdAccount viewer

More about Role
With roles, users can manipulate entities such as campaigns or products. Role is a set of permissions. Each role has different permissions and here will cover what we can do with each role briefly.

  • WORKPLACE_OWNER: Can manipulate almost all entities in the workplace
  • AD_ACCOUNT_OWNER: Can manipulate almost all entities in the ad account
  • AD_ACCOUNT_MEMBER: Can manipulate almost all entities in the ad account. But can not manipulate auth related entities and an ad account itself.
  • AD_ACCOUNT_VIEWER: Very limited. Can view campaigns and reports only.

Role Grant and Revoke

Here is the table of roles which can be granted by each role.

Role

Grantable roles

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

Here is the table of roles which can be revoked by each role.

Role

Revocable roles

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

Token

Token is not an entity. But it is important to understand. As other services do, the Auth API requires a bearer token. There is an API for issuing tokens. Token is bound to the workplace. If you want to manipulate other workplace’s entities then you need to issue a token for that workplace.

Entities Relationship

36443644

Fig 1. Overview of entities’ relationship

It’s important to understand entities’ relationships before moving on to APIs. As described in figure 1, there is a User entity and it can be registered to multiple workplaces (User A is registered to both workplace A and workplace B). But in most cases user is registered to a single workplace.

Users can have multiple roles. Role is bound to one of resources, Workplace or AdAccount. For example User A has a workplace owner role which is bound to workplace A (in the figure 1). And User A also has an ad account member role bound to AdAccount A. Users can have roles bound to the workplace to which only if they are registered.
But Users can have at most one role for one resource. For example, user can not have both ad account owner and ad account member roles bound to a Ad Account A.

Note that if the User has multiple roles, then the user's behavior is considered with the highest role. For example, if user A has a workplace owner role in Workplace A and an ad account role in AdAccount A then user A acts as workplace owner most of the time.

It is recommended to grant roles minimally. For example, if user A has a workplace owner role in Workplace A then user A does not have to have any role because workplace owner role is the highest one.