MOLOCO User API

openapi: 3.2.0
info:
  title: Moloco User API
  version: '1.0'
  description: 'Operations tagged User across 4 of this provider''s published API definitions: moloco-ads-campaign-management-api.json, moloco-ads-campaign-management-openapi.yml, moloco-cloud-auth-api.json, moloco-cloud-auth-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.moloco.cloud
- url: https://morse-us-prod.adsmoloco.com
tags:
- name: User
paths:
  /cm/v1/auth/ad-account/{ad_account_id}/users:
    get:
      summary: List ad account users
      description: 'List users under a certain ad account.

        With `include_role` query parameter, response can include roles.

        API callers who have a WORKPLACE_OWNER or AD_ACCOUNT_OWNER or AD_ACCOUNT_MEMBER role can call this API.'
      operationId: DspApi_ListAdAccountUsers
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messagesListAdAccountUsersResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
      parameters:
      - name: ad_account_id
        description: The ad account ID.
        in: path
        required: true
        schema:
          type: string
      - name: include_role
        description: Flag whether response includes user's role.
        in: query
        required: false
        schema:
          type: boolean
      tags:
      - User
      security:
      - Bearer: []
    servers:
    - url: https://api.moloco.cloud
  /cm/v1/auth/password:
    post:
      summary: Update user password
      description: 'Update user password.

        You can call this API with token whose type is AUTH_TOKEN, UPDATE_PASSWORD_TOKEN.'
      operationId: DspApi_UpdatePassword
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messagesUpdatePasswordResponse'
        default:
          description: 'Error. Detailed cause can be found in the `details` field.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messagesUpdatePasswordError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/messagesUpdatePasswordRequest'
        required: true
      tags:
      - User
      security:
      - Bearer: []
    servers:
    - url: https://api.moloco.cloud
  /cm/v1/auth/users:
    get:
      summary: List workplace users
      description: 'List users under a certain workplace.

        With `include_role` query parameter, response can include roles.

        Only API callers who have a WORKPLACE_OWNER role can call this API.'
      operationId: DspApi_ListWorkplaceUsers
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messagesListWorkplaceUsersResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
      parameters:
      - name: include_role
        description: Flag whether response includes user's role.
        in: query
        required: false
        schema:
          type: boolean
      - name: filter_roles
        description: "Filter the users who have this role.\nIf multiple roles are given, users who have one of these roles are filtered.\n\n - WORKPLACE_OWNER: Workplace owner represents a user who can do anything in a given workplace.\n - AD_ACCOUNT_OWNER: Ad account owner represents a user who can do anything in a given ad account.\n - AD_ACCOUNT_MEMBER: Ad account member can view all users of the Ad Account.\nCan invite new users as Ad Account Member or Ad Account Viewer\nCan edit your own information (ex: name)\nCan create and edit ad campaigns\n - AD_ACCOUNT_VIEWER: Ad account Viewer role offers a limited set of permissions that allows users\nonly to read the basic information of the resources."
        in: query
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - WORKPLACE_OWNER
            - AD_ACCOUNT_OWNER
            - AD_ACCOUNT_MEMBER
            - AD_ACCOUNT_VIEWER
      - name: match_roles
        description: "Select the users who have this role.\nIf multiple roles are given, only users who have all of these roles are selected.\n\n - WORKPLACE_OWNER: Workplace owner represents a user who can do anything in a given workplace.\n - AD_ACCOUNT_OWNER: Ad account owner represents a user who can do anything in a given ad account.\n - AD_ACCOUNT_MEMBER: Ad account member can view all users of the Ad Account.\nCan invite new users as Ad Account Member or Ad Account Viewer\nCan edit your own information (ex: name)\nCan create and edit ad campaigns\n - AD_ACCOUNT_VIEWER: Ad account Viewer role offers a limited set of permissions that allows users\nonly to read the basic information of the resources."
        in: query
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - WORKPLACE_OWNER
            - AD_ACCOUNT_OWNER
            - AD_ACCOUNT_MEMBER
            - AD_ACCOUNT_VIEWER
      tags:
      - User
      security:
      - Bearer: []
    servers:
    - url: https://api.moloco.cloud
  /cm/v1/auth/users/complete-signup:
    post:
      summary: Complete user signup
      description: 'Complete the user signup with additional info.

        The bearer token should be the password reset token which is achieved from `create password email`.

        Once this API succeeds, the user’s signed_up status becomes true.'
      operationId: DspApi_CompleteSignup
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messagesCompleteSignupResponse'
        default:
          description: Error. Detailed cause can be found in the `details` field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messagesCompleteSignupError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/messagesCompleteSignupRequest'
        required: true
      tags:
      - User
      security:
      - Bearer: []
    servers:
    - url: https://api.moloco.cloud
  /cm/v1/auth/users/expel:
    post:
      summary: Expel the user
      description: 'Expel the user from an API callers’ workplace.

        Only API callers who have the WORKPLACE_OWNER role can expel users.

        Expelled users will no longer have any roles under the workplace.'
      operationId: DspApi_ExpelUser
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messagesExpelUserResponse'
        default:
          description: Error. Detailed cause can be found in the `details` field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messagesExpelUserError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/messagesExpelUserRequest'
        required: true
      tags:
      - User
      security:
      - Bearer: []
    servers:
    - url: https://api.moloco.cloud
  /cm/v1/auth/users/forgot-password:
    post:
      summary: Forgot user password
      description: 'If the user forgot the password, use this API to receive `password reset email`.

        The `password reset email` contains password reset token for updating password and user’s email which will be used to call `UpdatePassword` API.

        The token is valid for 7 days.'
      operationId: DspApi_ForgotPassword
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messagesForgotPasswordResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/messagesForgotPasswordRequest'
        required: true
      tags:
      - User
      security: []
    servers:
    - url: https://api.moloco.cloud
  /cm/v1/auth/users/invite:
    post:
      summary: Invite the user
      description: 'Invite the user to an API callers’ workplace.

        The user who has WORKPLACE_OWNER or AD_ACCOUNT_OWNER or AD_ACCOUNT_MEMBER Roles can invite users to a workplace.'
      operationId: DspApi_InviteUser
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messagesInviteUserResponse'
        default:
          description: Error. Detailed cause can be found in the `details` field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messagesInviteUserError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/messagesInviteUserRequest'
        required: true
      tags:
      - User
      security:
      - Bearer: []
    servers:
    - url: https://api.moloco.cloud
  /cm/v1/auth/users/reset-password:
    post:
      summary: Reset the user password
      description: 'reset the user password.

        The bearer token should be the password reset token which is achieved from `password reset email`.

        Once this API succeeds, the user’s signed_up status becomes true.'
      operationId: DspApi_ResetPassword
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messagesResetPasswordResponse'
        default:
          description: Error. Detailed cause can be found in the `details` field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messagesResetPasswordError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/messagesResetPasswordRequest'
        required: true
      tags:
      - User
      security:
      - Bearer: []
    servers:
    - url: https://api.moloco.cloud
  /cm/v1/auth/users/withdrawal:
    post:
      summary: Delete the user
      description: 'Delete the user.

        '
      operationId: DspApi_DeleteUser
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messagesDeleteUserResponse'
        default:
          description: Error. Detailed cause can be found in the `details` field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messagesDeleteUserError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/messagesDeleteUserRequest'
        required: true
      tags:
      - User
      security: []
    servers:
    - url: https://api.moloco.cloud
  /cm/v1/auth/users/{user_id}:
    get:
      summary: Read the user
      description: 'Read the user under API caller''s workplace.

        If include_role specified, response will include roles bound to API caller''s workplace and ad account (if exists).

        The user who has any role except AD_ACCOUNT_VIEWER can call this API.

        A user who has an AD_ACCOUNT_VIEWER role can only read itself.'
      operationId: DspApi_ReadUser
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messagesReadUserResponse'
        default:
          description: Error. Detailed cause can be found in the `details` field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messagesReadUserError'
      parameters:
      - name: user_id
        description: The user ID.
        in: path
        required: true
        schema:
          type: string
      - name: include_role
        description: Flag whether response includes user's role.
        in: query
        required: false
        schema:
          type: boolean
      tags:
      - User
      security:
      - Bearer: []
    put:
      summary: Update the user
      description: Update the user's info such as name.
      operationId: DspApi_UpdateUser
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messagesUpdateUserResponse'
        default:
          description: Error. Detailed cause can be found in the `details` field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messagesUpdateUserError'
      parameters:
      - name: user_id
        description: The user ID.
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user:
                  $ref: '#/components/schemas/dspUser'
                  description: The user.
              required:
              - user
        required: true
      tags:
      - User
      security:
      - Bearer: []
    servers:
    - url: https://api.moloco.cloud
  /cm/v1/auth/workplaces:
    get:
      summary: List API caller's registered workplaces
      description: List workplaces to which the user has registered.
      operationId: DspApi_ListWorkplaces
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messagesListWorkplacesResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
      parameters:
      - name: show_history
        description: 'Flag to include creation request histories.

          If true, the response will include Workplace creation request histories.

          If false, the response will not include Workplace creation request histories.'
        in: query
        required: false
        schema:
          type: boolean
      tags:
      - User
      security:
      - Bearer: []
    servers:
    - url: https://api.moloco.cloud
  /cm/v1/auth/workplaces-by-domain:
    get:
      summary: List workplaces by domain with invitation status
      description: List workplaces by domain with the info whether API caller requested an invitation to this workplace or not.
      operationId: DspApi_ListWorkplacesByDomain
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messagesListWorkplacesByDomainResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
      tags:
      - User
      security:
      - Bearer: []
    servers:
    - url: https://api.moloco.cloud
  /v1/users:
    get:
      security:
      - Bearer: []
      description: List users matching the given condition.
      tags:
      - User
      summary: List users.
      operationId: v1_list_users
      parameters:
      - description: The ID of the platform to search users.
        name: platform_id
        in: query
        schema:
          type: string
      - description: The ID of the userspace to search users.
        name: userspace_id
        in: query
        schema:
          type: string
      - description: The email address of a user to search.
        name: email
        in: query
        schema:
          type: string
      - description: The name of the users to search.
        name: name
        in: query
        schema:
          type: string
      - description: Filter the users with this role.
        name: filter_role
        in: query
        explode: true
        schema:
          type: array
          items:
            type: string
      - description: Select the users with this role.
        name: match_role
        in: query
        explode: true
        schema:
          type: array
          items:
            type: string
      - description: 'If set to true, the role names granted to each user will be returned as well.

          When this parameter is used, the platform_id should be given as well because

          role grant is done under a specific platform.

          '
        name: with_roles
        in: query
        schema:
          type: boolean
      - description: If set to true, the status of each user will be returned as well.
        name: with_status
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: The list of users found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/listUsersResponse'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden - the user is not authorized to call this API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
    post:
      security:
      - Bearer: []
      description: Create a new user in a given userspace.
      tags:
      - User
      summary: Create a new user.
      operationId: v1_create_user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createUserRequest'
        description: a request to create a user.
        required: true
      responses:
        '200':
          description: The given user is successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/createUserResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden - the user is not authorized to call this API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '409':
          description: Conflict - the user is already there.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
    servers:
    - url: https://morse-us-prod.adsmoloco.com
  /v1/users/{email}/password:
    put:
      security:
      - Bearer: []
      description: Update the user password with the given password reset token in the header.
      tags:
      - User
      summary: Update the user password.
      operationId: v1_update_user_password
      parameters:
      - description: The email address of the user.
        name: email
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              required:
              - password
              properties:
                password:
                  description: Password to update.
                  type: string
        required: true
      responses:
        '204':
          description: The password is successfully updated.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden - cannot update permission because of lack of permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Not found - no such user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
    delete:
      description: Reset the user password and issue a password reset token.
      tags:
      - User
      summary: Delete the user password.
      operationId: v1_delete_user_password
      parameters:
      - description: The email address of the user.
        name: email
        in: path
        required: true
        schema:
          type: string
      - description: Userspace ID.
        name: userspace_id
        in: query
        required: true
        schema:
          type: string
      - description: Forward URL that will be included in the password reset email.
        name: forward_url
        in: query
        required: true
        schema:
          type: string
      responses:
        '204':
          description: The password reset email is sent to the user.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Not found - no such user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
    servers:
    - url: https://morse-us-prod.adsmoloco.com
  /v1/users/{user_id}:
    get:
      security:
      - Bearer: []
      description: Read a user information in the given userspace.
      tags:
      - User
      summary: Read a user.
      operationId: v1_read_user
      parameters:
      - description: The ID of the user, which can be Morse UID or email address.
        name: user_id
        in: path
        required: true
        schema:
          type: string
      - description: The userspace ID to which the user belongs.
        name: userspace_id
        in: query
        schema:
          type: string
      - description: The platform ID to which the user is registered.
        name: platform_id
        in: query
        schema:
          type: string
      - description: 'Get the role names bound to the user as well.

          This param should be used with platform_id.

          '
        name: with_roles
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: The user info was successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/readUserResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden - the user is not authorized to call this API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Not found - no such user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
    put:
      security:
      - Bearer: []
      description: Update an existing user matching the given user ID.
      tags:
      - User
      summary: Update an existing user.
      operationId: v1_update_user
      parameters:
      - description: The ID of the user.
        name: user_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateUserRequest'
        description: a request to update a user.
        required: true
      responses:
        '200':
          description: The user info was successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/updateUserResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Unauthorized - the given current password is not matching with the database record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden - the user is not authorized to call this API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Not found - no such user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
    delete:
      security:
      - Bearer: []
      description: Delete a user matching the user ID in a specific userspace.
      tags:
      - User
      summary: Delete a user.
      operationId: v1_delete_user
      parameters:
      - description: The ID of the user.
        name: user_id
        in: path
        required: true
        schema:
          type: string
      - description: The userspace ID.
        name: userspace_id
        in: query
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No user record found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden - the user is not authorized to call this API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Not found - no such user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
    servers:
    - url: https://morse-us-prod.adsmoloco.com
  /v1/users/{user_id}/permissions:
    get:
      security:
      - Bearer: []
      description: List the permissions given to the user.
      tags:
      - User
      summary: List the user permissions.
      operationId: v1_list_permissions
      parameters:
      - description: The ID of the user.
        name: user_id
        in: path
        required: true
        schema:
          type: string
      - description: The ID of the platform to which the user belongs.
        name: platform_id
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The list of permissions are correctly returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/listUserPermissionsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden - the user is not authorized to call this API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
    servers:
    - url: https://morse-us-prod.adsmoloco.com
  /v1/users/{user_id}/platforms/{platform_id}:
    post:
      security:
      - Bearer: []
      description: Register a user to a specific workplace.
      tags:
      - User
      summary: Add a user to a workplace.
      operationId: v1_register_user_to_platform
      parameters:
      - description: The ID of the user.
        name: user_id
        in: path
        required: true
        schema:
          type: string
      - description: The ID of the platform to which the user will be registered.
        name: platform_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/userRegistrationRequest'
      responses:
        '204':
          description: The registration was successfully finished.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden - not authorized to register a user to a platform.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '409':
          description: The registration was done already.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
    delete:
      security:
      - Bearer: []
      description: Deregister the given user from a specific workplace.
      tags:
      - User
      summary: Remove the user from a workplace.
      operationId: v1_delete_user_from_platform
      parameters:
      - description: The ID of the user.
        name: user_id
        in: path
        required: true
        schema:
          type: string
      - description: The ID of the platform from which the user will be removed.
        name: platform_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description

# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/moloco/refs/heads/main/openapi/moloco-user-api-openapi.yml