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 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'
  /v1/users/{user_id}/platforms/{platform_id}:
    post:
      security:
      - Bearer: []
      description: Register a user to a specific workplace.
      tags:
      - User
      - Workplace
      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
      - Workplace
      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: The registration was successfully deleted.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden - not authorized to remove the user from the platform.
          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}/rolegrants:
    get:
      security:
      - Bearer: []
      description: Get the list of role grants to the given user.
      tags:
      - User
      - RoleGrant
      summary: Get role grants.
      operationId: v1_list_role_grants
      parameters:
      - description: The ID of the user.
        name: user_id
        in: path
        required: true
        schema:
          type: string
      - description: Platform ID.
        name: platform_id
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The list of roles granted to the given user was successfully returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/listRoleGrantsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden - not authorized to list roles granted.
          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 role grant that attaches roles to a resource and a user.
      tags:
      - User
      - RoleGrant
      summary: Create a role grant.
      operationId: v1_create_role_grants
      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/createRoleGrantsRequest'
        description: The request body
        required: true
      responses:
        '204':
          description: The roles are successfully granted.
        '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 role grant is already there.
          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 specific role attached to a specific resource.
      tags:
      - User
      - RoleGrant
      summary: Delete a role grant.
      operationId: v1_delete_role_grants
      parameters:
      - 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
      - description: The resource to which the role is granted.
        name: resource_id
        in: query
        required: true
        schema:
          type: string
      - description: The actual instance ID of the resource.
        name: resource_instance_id
        in: query
        required: true
        schema:
          type: string
      - description: The ID of the granted role.
        name: role_id
        in: query
        required: true
        schema:
          type: string
      - description: The ID of the platform in which the role is defined.
        name: role_platform_id
        in: query
        required: true
        schema:
          type: string
      responses:
        '204':
          description: The role grant was successfully deleted.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden - not authorized to list roles granted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /v1/userspaces/{userspace_id}/platforms:
    post:
      security:
      - Bearer: []
      - {}
      description: List workplaces for a given userspace.
      tags:
      - Userspace
      - Workplace
      summary: List workplaces.
      operationId: v1_list_userspace_platforms
      parameters:
      - description: The ID of the userspace.
        name: userspace_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/listPlatformsCredential'
        description: a user credential to list platforms for the user.
      responses:
        '200':
          description: The list of platforms.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/listPlatformsResponse'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Unauthorized - the given user_id/password is not matched.
          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: No such user found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
x-google-backend:
  address: https://morse-us-prod.adsmoloco.com
servers:
- url: https://morse-us-prod.adsmoloco.com
components:
  securitySchemes:
    Bearer:
      type: apiKey
      name: Authorization
      in: header
  schemas:
    adAccountRegistration:
      description: A user registered to an Ad Account.
      type: object
      required:
      - id
      - ad_account_id
      - ad_account_title
      properties:
        ad_account_id:
          description: The Ad Account to which the user is registered.
          type: string
        ad_account_title:
          description: The display name of the Ad Account.
          type: string
        id:
          description: The user ID.
          type: string
    adAccountRegistrationWithUserInfo:
      description: A user registered to an Ad Account and the roles given to the user for the Ad Account.
      type: object
      allOf:
      - $ref: '#/components/schemas/adAccountRegistration'
      - properties:
          roles:
            type: array
            items:
              $ref: '#/components/schemas/roleReference'
          status:
            $ref: '#/components/schemas/userStatus'
          user_email:
            type: string
          user_name:
            type: string
    createAdAccountRegistrationRequest:
      description: A request to register a user to an Ad Account.
      type: object
      required:
      - platform_id
      - registration
      properties:
        forward_url:
          description: The URL that should be included in the invitation email.
          type: string
        platform_id:
          description: The platform ID.
          type: string
        registration:
          $ref: '#/components/schemas/adAccountRegistration'
    createPlatformRequest:
      description: Request to create a platform.
      type: object
      required:
      - platform
      properties:
        platform:
          $ref: '#/components/schemas/platform'
    createPlatformResponse:
      description: Response to a request to create a platform.
      type: object
      required:
      - platform
      properties:
        platform:
          $ref: '#/components/schemas/platform'
    createRmpAdAccountRegistrationRequest:
      description: A request to register a user to an Ad Account.
      type: object
      required:
      - platform_id
      - registration
      properties:
        platform_id:
          description: The platform ID.
          type: string
        registration:
          $ref: '#/components/schemas/rmpAdAccountRegistration'
    createRoleGrantsRequest:
      description: Request to attach roles to a resource and a user.
      type: object
      required:
      - platform_id
      - resource_id
      - resource_instance_id
      - roles
      properties:
        platform_id:
          description: The ID of the platform in which the role grant is made.
          type: string
        resource_id:
          description: Resource ID to which the roles are granted.
          type: string
        resource_instance_id:
          description: The actual instance ID of the resource to which the roles are granted.
          type: string
        roles:
          description: The list of roles granted to the resource.
          type: array
          items:
            $ref: '#/components/schemas/roleReference'
    createTokenRequest:
      description: A request to create a token
      type: object
      required:
      - workplace_id
      - email
      - password
      properties:
        email:
          description: The email address of the user.
          type: string
        password:
          description: The password of the user.
          type: string
        workplace_id:
          description: The ID of the workplace to which the user belongs.
          type: string
    createTokenResponse:
      description: A response to CreateTokenRequest
      type: object
      required:
      - token
      - user
      properties:
        token:
          description: The successfully issued Morse token.
          type: string
        user:
          $ref: '#/components/schemas/user'
    createUserRequest:
      description: A request to create a user.
      type: object
      required:
      - user
      properties:
        forward_url:
          description: A URL that will be included in the Welcome email.
          type: string
        user:
          $ref: '#/components/schemas/user'
    createUserResponse:
      description: A response to a create user request.
      type: object
      required:
      - user
      properties:
        user:
          $ref: '#/components/schemas/user'
    error:
      description: Error response with detailed reason.
      type: object
      required:
      - reason
      - status
      properties:
        reason:
          description: More detailed reason about why the error was returned.
          type: string
        status:
          description: The error status code.
          type: integer
    healthCheckResponse:
      description: A response to a health check request.
      type: object
      required:
      - healthy
      properties:
        healthy:
          description: Indicates whether the server is healthy or not.
          type: boolean
    listAdAccountRegistrationsResponse:
      description: Lists the user registrations to an Ad Account with roles assigned to each user.
      type: object
      required:
      - registrations
      properties:
        registrations:
          description: The user registrations to an Ad Account with user roles.
          type: array
          items:
            $ref: '#/components/schemas/adAccountRegistrationWithUserInfo'
    listPlatformsCredential:
      description: Credential to list platforms without a Morse token.
      type: object
      required:
      - email
      - password
      properties:
        email:
          description: Email address of the user.
          type: string
        password:
          description: Password of the user.
          type: string
    listPlatformsResponse:
      description: Response to the list platforms request.
      type: object
      required:
      - platforms
      properties:
        platforms:
          description: List of platforms
          type: array
          items:
            $ref: '#/components/schemas/platform'
    listRmpAdAccountRegistrationsResponse:
      description: Lists the user registrations to an Ad Account with roles assigned to each user.
      type: object
      required:
      - registrations
      properties:
        registrations:
          description: The user registrations to an Ad Account with user roles.
          type: array
          items:
            $ref: '#/components/schemas/rmpAdAccountRegistrationWithUserInfo'
    listRoleGrantsResponse:
      description: List of roles granted to a user.
      type: object
      required:
      - role_grants
      properties:
        role_grants:
          description: list of role grants.
          type: array
          items:
            $ref: '#/components/schemas/resourceToRoleReferences'
    listUserPermissionsResponse:
      description: The API response that lists the permissions that the user has.
      type: object
      required:
      - user_id
      - platform_id
      - userspace_id
      - resource_path_permissions
      properties:
        platform_id:
          description: The ID of the platform to which the user belongs to.
          type: string
        resource_path_permissions:
          description: The resource path and the permissions given to the path.
          type: array
          items:
            $ref: '#/components/schemas/resourcePathPermissions'
        user_id:
          description: The ID of the user.
          type: string
        userspace_id:
          description: The ID of the userspace to which the platform belongs to.
          type: string
    listUsersResponse:
      description: A response to list users with the given condition.
      type: object
      properties:
        users:
          description: Users found
          type: array
          items:
            $ref: '#/components/schemas/user'
    permission:
      description: Permission.
      type: object
      required:
      - id
      - platform_id
      - service
      - resource_id
      - verb
      properties:
        id:
          description: The ID of the permission.
          type: string
        name:
          description: The name of the permission.
          type: string
        platform_id:
          description: The platform ID in which the permission is defined.
          type: string
        resource_id:
          description: The resource on which the permission is defined.
          type: string
        service:
          description: The name of the service such as DSP, AUTH.
          type: string
        verb:
          description: The action that the permision controls, such as CREATE, REVOKE, ADMIN.
          type: string
    platform:
      description: A platform.
      type: object
      required:
      - id
      - userspace_id
      - title
      - logo_url
      properties:
        configuration:
          description: The platform-specific configuration.
          type: object
          additionalProperties:
            type: string
        id:
          description: The ID of the platform.
          type: string
        logo_url:
          description: The URL of the logo for the platform.
          type: string
        title:
          description: The user-friendly name of the platform.
          type: string
        userspace_id:
          description: The ID of the userspace to which the platform belongs.
          type: string
    readPlatformResponse:
      description: Response to read a platform information.
      type: object
      required:
      - platform
      properties:
        platform:
          $ref: '#/components/schemas/platform'
    readUserResponse:
      description: A response to a read user request.
      type: object
      required:
      - user
      properties:
        user:
          $ref: '#/components/schemas/user'
    resourcePathPermissions:
      description: A resource path and the permissions given to it.
      type: object
      required:
      - id
      - instance_id
      - permissions
      properties:
        id:
          description: Resource ID.
          type: string
        instance_id:
          description: Resource instance ID.
          type: string
        permissions:
          description: Permissions given to the resource.
          type: array
          items:
            $ref: '#/components/schemas/permission'
    resourceToRoleReferences:
      description: Relationship between a resource and a list of roles.
      type: object
      required:
      - resource_id
      - resource_instance_id
      - roles
      properties:
        resource_id:
          description: Resource ID to which the roles are granted.
          type: string
        resource_instance_id:
          description: The actual instance ID of the resource to which the roles are granted.
          type: string
        roles:
          description: The list of roles granted to the resource.
          type: array
          items:
            $ref: '#/components/schemas/roleReference'
    rmpAdAccountRegistration:
      description: A user registered to an Ad Account.
      type: object
      required:
      - id
      - ad_account_id
      - ad_account_title
      properties:
        ad_account_id:
          description: The Ad Account to which the user is registered.
          type: string
        ad_account_title:
          description: The display name of the Ad Account.
          type: string
        id:
          description: The user ID.
          type: string
    rmpAdAccountRegistrationWithUserInfo:
      description: A user registered to an Ad Account and the roles given to the user for the Ad Account.
      type: object
      allOf:
      - $ref: '#/components/schemas/rmpAdAccountRegistration'
      - properties:
          roles:
            type: array
            items:
              $ref: '#/components/schemas/resourceToRoleReferences'
          status:
            $ref: '#/components/schemas/userStatus'
          user_email:
            type: string
          user_name:
            type: string
    roleReference:
      description: Reference to a role defined in a platform.
      type: object
      required:
      - id
      - platform_id
      properties:
        id:
          description: The ID of the role.
          type: string
        platform_id:
          description: The platofrm ID where the role is defined.
          type: string
    updatePasswordRequest:
      description: A request to update a user password.
      type: object
      required:
      - current_password
      - new_password
      properties:
        current_password:
          description: The current user password.
          type: string
        new_password:
          description: The new user password.
          type: string
    updatePlatformRequest:
      description: A request to update a platform.
      type: object
      required:
      - platform
      properties:
        platform:
          $ref: '#/components/schemas/platform'
    updatePlatformResponse:
      description: Response to a request to update a platform.
      type: object
      required:
      - platform
      properties:
        platform:
          $ref: '#/components/schemas/platform'
    updateUserRequest:
      description: A request to update a user.
      type: object
      required:
      - userspace_id
      properties:
        configuration:
          description: Per-user configuration to update.
          type: object
          additionalProperties:
            type: string
        name:
          description: Name to update.
          type: string
        password:
          $ref: '#/components/schemas/updatePasswordRequest'
        userspace_id:
          description: A userspace ID where the user is.
          type: string
    updateUserResponse:
      description: A response to an update user request.
      type: object
      required:
      - user
      properties:
        user:
          $ref: '#/components/schemas/user'
    user:
      description: A user.
      type: object
      required:
      - userspace_id
      - email
      - name
      properties:
        configuration:
          description: Per-user configuration (key-value pairs).
          type: object
          additionalProperties:
            type: string
        created_at:
          description: The time when the user is created.
          type: string
          format: date-time
          readOnly: true
        email:
          description: The email address of the user.
          type: string
          format: email
        id:
          description: 'The ID of the user. You don''t need to specify this value when creating a user.

            The ID will be automatically determined by Morse.

            '
          type: string
        name:
          description: The name of the user.
          type: string
        password:
          description: The sign-in password of the user.
          type: string
        role_grants:
          description: The list of specific roles granted to the user. Returned only when explicitly asked.
          type: array
          items:
            $ref: '#/components/schemas/resourceToRoleReferences'
          x-omitempty: true
          readOnly: true
        roles:
          description: The list of roles assigned to the user. Returned only when explicitly asked.
          type: array
          items:
            $ref: '#/components/schemas/roleReference'
          x-omitempty: true
          readOnly: true
        status:
          $ref: '#/components/schemas/userStatus'
        updated_at:
          description: The time when the user information is updated.
          type: string
          format: date-time
          readOnly: true
        userspace_id:
          description: The ID of the user space such as USERSPACE_C.
          type: string
    userRegistrationRequest:
      description: The request body for the user registration request.
      type: object
      properties:
        forward_url:
          description: the URL that will be included in the platform registration (sign-up) email.
          type: string
    userStatus:
      description: The set of status values for a user.
      type: object
      required:
      - signed_up
      properties:
        signed_up:
          description: The signed up status of the user.
          type: boolean