Auth

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 the 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.

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 general to Workplace or AdAccount. (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 entities under the Workplace
AD_ACCOUNT_OWNER: Can manipulate entities under the AdAccount
AD_ACCOUNT_MEMBER: Can manipulate entities under the AdAccount. Cannot manipulate auth related entities and an AdAccount itself.
AD_ACCOUNT_VIEWER: 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. Our APIs require a bearer token for authentication and authorization. You can use TokenAPI to generate a new token. Token has 1 hour expiration so you can use RefreshTokenAPI to refresh the token. One more thing you should be aware of is that our token is bound to the workplace, and if you want to manipulate other Workplace’s entities then you need to issue a new token dedicated for that workplace.

Entities Relationship

3644 — 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.