Moloco Cloud Auth API

openapi: 3.0.0
info:
  description: 'MOLOCO Cloud Auth API provides functionalities to authenticate and authorize the MOLOCO Cloud users.

    '
  title: MOLOCO Cloud Auth API
  version: 1.0.0
paths:
  /ready:
    get:
      description: Check the health of the MOLOCO Cloud Auth API service.
      tags:
      - Health
      summary: Check the health of the service.
      operationId: v1_health_check
      responses:
        '200':
          description: The API is working  file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/healthCheckResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /v1/ad-accounts/{ad_account_id}/users:
    get:
      security:
      - Bearer: []
      description: Get the list of users registered to the given ad account.
      tags:
      - AdAccount
      summary: Get the list of ad account users.
      operationId: v1_list_ad_account_registrations
      parameters:
      - description: The Ad Account ID.
        name: ad_account_id
        in: path
        required: true
        schema:
          type: string
      - description: Platform ID.
        name: platform_id
        in: query
        required: true
        schema:
          type: string
      - description: If given, the result will include the user status info.
        name: with_status
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: The list of users that the advertiser has.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/listAdAccountRegistrationsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden - not authorized to list users.
          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: Register a user to an ad account in the same workplace.
      tags:
      - AdAccount
      summary: Register a user to an ad account.
      operationId: v1_create_ad_account_registration
      parameters:
      - description: The Ad Account ID.
        name: ad_account_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createAdAccountRegistrationRequest'
        description: The request body
        required: true
      responses:
        '204':
          description: The user is successfully registered to the advertiser.
        '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 registered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /v1/ad-accounts/{ad_account_id}/users/{user_id}:
    delete:
      security:
      - Bearer: []
      description: Delete the user registration to an a specific ad account.
      tags:
      - AdAccount
      summary: Remove a user from an ad account.
      operationId: v1_delete_ad_account_registration
      parameters:
      - description: The Ad Account to which the user was registered.
        name: ad_account_id
        in: path
        required: true
        schema:
          type: string
      - description: The ID of the user.
        name: user_id
        in: path
        required: true
        schema:
          type: string
      - description: The platform ID to which the user belongs.
        name: platform_id
        in: query
        required: true
        schema:
          type: string
      responses:
        '204':
          description: The user is successfully removed from the Ad Account.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden - not authorized to delete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /v1/platforms:
    post:
      security:
      - Bearer: []
      description: Create a workplace for the campaign management.
      tags:
      - Workplace
      summary: Create a workplace.
      operationId: v1_create_platform
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createPlatformRequest'
        description: a request to create a platform.
        required: true
      responses:
        '200':
          description: The platform is successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/createPlatformResponse'
        '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 platform is already there.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /v1/platforms/{platform_id}:
    get:
      security:
      - Bearer: []
      description: Read a workplace information for the given workplace ID.
      tags:
      - Workplace
      summary: Read a workplace information.
      operationId: v1_read_platform
      parameters:
      - description: The platform ID.
        name: platform_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The platform info is successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/readPlatformResponse'
        '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 platform.
          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 a workplace information with the given new information.
      tags:
      - Workplace
      summary: Update a workplace information.
      operationId: v1_update_platform
      parameters:
      - description: The platform ID.
        name: platform_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updatePlatformRequest'
        description: a request to update a platform.
        required: true
      responses:
        '200':
          description: The platform is successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/updatePlatformResponse'
        '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 platform.
          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 workplace for the given workplace ID.
      tags:
      - Workplace
      summary: Delete a workplace.
      operationId: v1_delete_platform
      parameters:
      - description: The platform ID.
        name: platform_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: The platform is successfully deleted.
        '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 platform.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /v1/platforms/{platform_id}/logo:
    post:
      security:
      - Bearer: []
      description: Upload the workplace logo to the public bucket and update the workplace database record.
      tags:
      - Workplace
      summary: Upload the workplace logo.
      operationId: v1_upload_platform_logo
      parameters:
      - description: The platform ID.
        name: platform_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                logo:
                  description: The logo file to upload.
                  type: string
                  format: binary
              required:
              - logo
        required: true
      responses:
        '200':
          description: The workplace logo is successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/updatePlatformResponse'
        '400':
          description: Bad request including bad content type other than multipart/form-data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden - no permission to use this API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Not found - no such workplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /v1/rmp-ad-accounts/{ad_account_id}/users:
    get:
      security:
      - Bearer: []
      description: Get the list of users registered to the given ad account.
      tags:
      - RmpAdAccount
      operationId: v1_list_rmp_ad_account_registrations
      parameters:
      - description: The Ad Account ID.
        name: ad_account_id
        in: path
        required: true
        schema:
          type: string
      - description: Platform ID.
        name: platform_id
        in: query
        required: true
        schema:
          type: string
      - description: If given, the result will include the user status info.
        name: with_status
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: The list of users that the advertiser has.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/listRmpAdAccountRegistrationsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden - not authorized to list users.
          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: Register a user to an rmp ad account in the same workplace.
      tags:
      - RmpAdAccount
      summary: Register a user to an ad account.
      operationId: v1_create_rmp_ad_account_registration
      parameters:
      - description: The Ad Account ID.
        name: ad_account_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createRmpAdAccountRegistrationRequest'
        description: The request body
        required: true
      responses:
        '204':
          description: The user is successfully registered to the advertiser.
        '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 registered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /v1/rmp-ad-accounts/{ad_account_id}/users/{user_id}:
    delete:
      security:
      - Bearer: []
      description: Delete the user registration to an a specific ad account.
      tags:
      - RmpAdAccount
      summary: Remove a user from an ad account.
      operationId: v1_delete_rmp_ad_account_registration
      parameters:
      - description: The Ad Account to which the user was registered.
        name: ad_account_id
        in: path
        required: true
        schema:
          type: string
      - description: The ID of the user.
        name: user_id
        in: path
        required: true
        schema:
          type: string
      - description: The platform ID to which the user belongs.
        name: platform_id
        in: query
        required: true
        schema:
          type: string
      responses:
        '204':
          description: The user is successfully removed from the Ad Account.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden - not authorized to delete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /v1/tokens:
    put:
      security:
      - Bearer: []
      description: Issue a new token with a previous one. Expired tokens cannot be refreshed.
      tags:
      - Token
      summary: Refresh the existing token.
      operationId: v1_refresh_token
      responses:
        '200':
          description: The token was successfully refreshed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/createTokenResponse'
        '400':
          description: Bad Request.
          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'
    post:
      description: Create a new token to access MOLOCO APIs. The token is valid for one hour. Therefore, it is recommended
        to periodically refresh the token before it expires.
      tags:
      - Token
      summary: Create a new token.
      operationId: v1_create_token
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createTokenRequest'
        description: a request to create a token.
        required: true
      responses:
        '200':
          description: The token was successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/createTokenResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Unauthorized - the given credentials are wrong.
          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'
  /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'
  /v1/users/{email}/password:
    put:
      security:
      - Bearer: []
      description: Update the user password with the given password reset token in the header.
      tags:
      - User
      - Password
      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
      - Password
      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'
  /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'
  /v1/users/{user_id}/permissions:
    get:
      security:
      - Bearer: []
      description: List the permissions given to the user.
      tags:
      - User
      - Permission
      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 be

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