Hellou AI Security Settings API

openapi: 3.2.0
info:
  title: HellouOne Security Settings API
  version: 1.0.0
  description: 'The HellouOne REST API: everything the dashboard does, available to your

    own systems — CRMs, bots, BI tools and back-office automation.'
  termsOfService: https://hellou.ai/en/legal/terms/
  contact:
    name: HellouOne support
    email: support@hellou.ai
servers:
- url: https://one.hellou.ai
  description: HellouOne cloud
security:
- userApiKey: []
tags:
- name: Security Settings
paths:
  /api/v1/accounts/{account_id}/security_settings:
    parameters:
    - $ref: '#/components/parameters/account_id'
    get:
      tags:
      - Security Settings
      operationId: getSecuritySettings
      summary: Get the account security settings
      description: 'Tells whether the account requires two-step verification (MFA) of every member, how many members the

        account has and how many of them have not set MFA up yet.


        **Administrators only.**'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/security_settings'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
    patch:
      tags:
      - Security Settings
      operationId: updateSecuritySettings
      summary: Require or stop requiring MFA for the account
      description: 'Turns the MFA requirement on or off for every member of the account. While it is on, a member who has

        not set up MFA gets `403` with `error` `mfa_setup_required` on this account''s endpoints (session token

        and `api_access_token` alike) until they turn MFA on in their profile. Members who sign in as a super

        admin impersonation are exempt. Each member''s MFA can then no longer be turned off while the requirement

        stands. Every change is recorded in the audit log.


        You must have MFA on yourself to turn the requirement on: otherwise the answer is `422` with

        `error: mfa_admin_setup_required`. Turning it on or off when it already is that way changes nothing.


        **Administrators only.**'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - mfa_enforced
              properties:
                mfa_enforced:
                  type: boolean
                  description: True to require MFA of every member, false to stop requiring it.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/security_settings'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '422':
          description: The administrator has not turned MFA on (`error` is `mfa_admin_setup_required`), or `mfa_enforced` is missing (`mfa_enforced_required`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
components:
  responses:
    unauthorized:
      description: Missing or invalid `api_access_token`, or a bot token on an endpoint bots cannot use.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_message'
    forbidden:
      description: 'Not allowed: the user''s role does not permit it, the feature is not enabled

        for the account (`reason: feature_disabled`), or the account is read-only.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_message'
  parameters:
    account_id:
      in: path
      name: account_id
      required: true
      description: The numeric ID of the account
      schema:
        type: integer
  schemas:
    security_settings:
      type: object
      description: Whether the account requires two-step verification (MFA) of every member, and how many members have not set it up yet.
      properties:
        mfa_enforced:
          type: boolean
          description: True when every member must have MFA on. A member without it gets `403` with `error` `mfa_setup_required` on this account's endpoints.
        members_total:
          type: integer
          description: How many members the account has.
        members_without_mfa:
          type: integer
          description: How many members have not turned MFA on. They are blocked as soon as the requirement is on.
      required:
      - mfa_enforced
      - members_total
      - members_without_mfa
    error_message:
      type: object
      description: An error with a human-readable message.
      properties:
        error:
          type: string
          description: What went wrong.
        reason:
          type: string
          description: Machine-readable cause, when there is one (for example `feature_disabled`).
      required:
      - error
  securitySchemes:
    userApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: 'A user''s access token, from **Profile settings → Access token** in the dashboard.

        Requests act with that user''s role: administrators reach everything in their

        account, agents only what their role and visibility settings allow.

        '
    agentBotApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: 'An agent bot''s access token, shown to administrators on the bot''s settings page.

        Bot tokens reach a limited set of conversation and message endpoints.

        '
    platformAppApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: 'A platform app token, issued by the installation operator. Used to provision

        accounts, users, account memberships and agent bots.

        '
    connectorInvokeToken:
      type: http
      scheme: bearer
      description: 'A connector''s invoke token (`hci_…`), sent as `Authorization: Bearer <token>`.

        Each connector install has its own; it is rotated whenever the connector is

        reconnected or disconnected, so a stale copy stops working.

        '
x-tagGroups:
- name: Guides
  tags:
  - Introduction
  - Authentication
  - Errors
  - Pagination
  - Rate limits
  - Webhook events
- name: Webhook payloads
  tags:
  - Event payloads
- name: Platform
  tags:
  - Accounts
  - Account Users
  - AgentBots
  - Users
- name: Application
  tags:
  - Account AgentBots
  - Agents
  - Automation Rule
  - Campaigns
  - Canned Responses
  - Contacts
  - Contact Labels
  - Conversation Assignment
  - Conversation Labels
  - Conversations
  - Custom Attributes
  - Custom Filters
  - Help Center
  - Inboxes
  - Integrations
  - Macros
  - Messages
  - Profile
  - Reports
  - Security Settings
  - Teams
  - Webhooks
- name: Business tools
  tags:
  - AI Classifications
  - Assignment Settings
  - Calls
  - AI Phone Lines
  - Connectors
  - ElevenLabs Integration
  - Facebook Marketing
  - HellouAI Integration
  - Knowledge Base
  - Marketing Consent
  - Plan Upgrades
  - Voice Campaigns
  - WhatsApp Campaigns
  - WhatsApp Flows
  - WhatsApp Templates
- name: Client
  tags:
  - Inbox API
  - Contacts API
  - Conversations API
  - Messages API
- name: Others
  tags:
  - CSAT Survey Page