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
There are several entities which are related to auth.
Workplace entity has an id and a title.
|id||string||Y||The workplace ID.|
|title||string||Y||The workplace title.|
User entity represents a single user.
|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 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)
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.
Here is the table of roles which can be granted by each role.
Here is the table of roles which can be revoked by each role.
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.
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.
Updated 4 months ago