Abnormal AI Users API

openapi: 3.2.0
info:
  title: Abnormal Security Client Users API
  version: 1.4.3
  description: 'This is the specification for Abnormal Security Client API which can be used for managing security threats detected by Abnormal Security.

    <h2>Who is this API for?</h2>

    This API is for managing threats to an organization identified by Abnormal Security. The organization should be integrated with Abnormal Security and enabled for real-time detection of malicious emails.

    <h2> Integration Steps </h2>

    Go to `https://portal.abnormalsecurity.com/home/settings/integrations` & click on `Abnormal REST API`

    <h3> Step 1: Generating the authentication token </h3>


    Retrieve your authentication token via the <a href="https://portal.abnormalsecurity.com/home/settings/integrations">Abnormal portal</a>. You will use this token to view and modify your Abnormal-detected threats and cases.


    Keep the token safe, as it grants access to sensitive threat data related to your organization. Store it in a secure place, such as an encrypted password vault, and do not share it unless absolutely necessary. If you feel that the token has been compromised, please contact your Account Manager immediately.


    Once obtained, the token can be used in a request from any HTTP client, such as cURL:

    <pre> curl -H "Authorization: Bearer  << ACCESS_TOKEN >>" https://api.abnormalplatform.com/v1/threats </pre>


    <h3> Step 2: IP allowlisting </h3>


    IP allowlisting ensures that API access is only possible from IP addresses explicitly belonging to your organization. It prevents users from unauthorized networks to access your Abnormal SOAR data. This second layer of security helps keep your data safe from unauthorized users, and protects you in the event of a token compromise.


    To allowlist your organization''s IPs, please provide enter into the <a href="https://portal.abnormalsecurity.com/home/settings/integrations">Abnormal portal</a> specific IPv4 / IPv6 addresses, or a range of addresses using a <a href="https://www.ipaddressguide.com/cidr"> CIDR block</a>.


    <h3> Step 3: Try it out with Test Data </h3>


    To confirm that <b>Steps 1 & 2</b> have been configured properly, send a request to the server with the following header set:


    <pre> curl -H "Authorization: Bearer  << ACCESS_TOKEN >>" <b>-H "Mock-Data: True"</b> https://api.abnormalplatform.com/v1/threats </pre>


    The server should respond with a body payload similar to the examples specified in this documentation.


    <h3> Note for EU Customers </h3>


    If you''re a customer in the EU, you''ll need to make API requests to our EU host `https://eu.rest.abnormalsecurity.com`. If you''d like to test the API through SwaggerHub, you''ll find both the default host and the EU host in the Servers dropdown menu below.

    '
  termsOfService: https://legal.abnormalsecurity.com/legal-hub/abnormal-security-api-terms-of-service-6feee5e3
  contact:
    name: Abnormal Security Support
    email: support@abnormalsecurity.com
servers:
- url: https://api.abnormalplatform.com/v1
  description: Production Server for managing threats
- url: https://eu.rest.abnormalsecurity.com/v1
  description: EU Production Server for managing threats.
security:
- BearerAuth: []
tags:
- name: Users
  description: API to retrieve users from RBAC system
paths:
  /users:
    get:
      operationId: v1_users_retrieve
      description: Retrieves users for an account from the RBAC user management system.
      summary: Get a list of users from RBAC user management system
      parameters:
      - in: header
        name: mock-data
        schema:
          type: string
          default: 'False'
          enum:
          - 'False'
          - 'True'
        description: Returns test data if set to `True`
      tags:
      - Users
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
          description: A list of users with their roles and resource permissions.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: Forbidden - Insufficient permissions
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
components:
  schemas:
    UserSwagger:
      type: object
      description: Swagger serializer for user object.
      properties:
        user_id:
          type: integer
          description: The unique identifier for the user
        email:
          type: string
          format: email
          description: Email address of the user
        groups:
          type: array
          items:
            type: string
          default: []
          description: List of group IDs the user belongs to
        local_login_enabled:
          type: boolean
          default: false
          description: Whether local login is enabled for the user
        sso_enabled:
          type: boolean
          default: true
          description: Whether SSO is enabled for the user
        role:
          allOf:
          - $ref: '#/components/schemas/RoleSwagger'
          description: Role assigned to the user with associated permissions
        resource_permissions:
          type: array
          items:
            $ref: '#/components/schemas/ResourcePermissionSwagger'
          description: List of resource permissions granted to the user through their role (only includes enabled permissions)
      required:
      - email
      - user_id
    PolicySwagger:
      type: object
      description: Swagger serializer for policy object within a role.
      properties:
        resource:
          type: string
          description: The resource name (e.g., 'threats', 'cases')
        permissions:
          type: array
          items:
            type: string
          description: List of permissions granted on this resource
      required:
      - permissions
      - resource
    UserListResponse:
      type: object
      description: Swagger serializer for user list response.
      properties:
        status:
          type: string
          default: success
          description: Status of the response
        status_code:
          type: integer
          default: 200
          description: HTTP status code
        data:
          type: array
          items:
            $ref: '#/components/schemas/UserSwagger'
          description: List of users from RBAC system with their roles and resource permissions
      required:
      - data
    RoleSwagger:
      type: object
      description: Swagger serializer for role object.
      properties:
        id:
          type: integer
          description: The unique identifier for the role
        name:
          type: string
          description: Name of the role
        description:
          type: string
          default: ''
          description: Description of the role
        policies:
          type: array
          items:
            $ref: '#/components/schemas/PolicySwagger'
          description: Simplified view of permissions granted by this role
      required:
      - id
      - name
      - policies
    ResourcePermissionSwagger:
      type: object
      description: Swagger serializer for resource permissions.
      properties:
        resource:
          type: string
          description: Name of the resource (e.g., 'ato', 'threat_log')
        permissions:
          type: array
          items:
            type: string
          description: List of permissions for this resource (e.g., 'view', 'write', 'manage')
      required:
      - permissions
      - resource
  responses:
    NotFoundError:
      description: Invalid user input when using the filter query parameter. Will return various error messages
    TooManyRequestsError:
      description: Request count exceeds allowed number of concurrent requests for this resource type
    UnauthorizedError:
      description: Access token is missing or invalid
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer