Unify Integrations - Unify API V1 Overview

⚠️ General Guidance & Expectations

The Unify API V1 is a REST/HTTP API and usage requires knowledge of REST/HTTP API conventions and semantics, and compliance with the API’s expectations and specifications.

🌐 Hosts

All Unify regions support the Unify API V1. The hostnames for the APIs are as follows:

All Endpoints listed below must be prefixed with /v1

📖 Content Types

The Unify API V1 currently supports JSON requests and responses only, though it may support content types other than JSON in the future for both request and response payloads.

All requests should include a "content-type: application/json" header, and all responses will include a "content-type: application/json" header. Any request made without this header will be rejected.

💬 Responses

Every request made to the Unify API V1 returns a response that includes a JSON body (documented below) as well as HTTP response codes and HTTP Headers. Clients of the Unify API V1 are expected to understand and respect all HTTP response codes below: 

The Unify API V1 enforces rate limits, both to prevent high bursts of requests at any given moment, and to limit the total number of requests that can be made in a day. Clients of the API are expected to respect the rate limits, and to back off when a rate limit is reached. As indicated in the Responses section above, all rate limited requests will return an HTTP code of 429.

Please talk with your Client Success Manager and Field Engineer about how to work within your rate limits, or to modify your rate limits.

🔬 Evolution

The Unify API V1 may evolve in time to include additional capabilities, which will be documented here. However, the API will be backward compatible with all API specifications documented here for the life of the API.

💾 Deprecation

The Unify API V1 may be deprecated in the future, in lieu of a new API (e.g., a V2) with different features and semantics. If the Unify API V1 is deprecated, your Client Success Manager and Field Engineer will notify of you of the deprecation well in advance of the API’s end of life date, and work with you to transition to the new/alternative API.

🗺️ Getting Started

To get started with the Unify API V1 please speak with your Client Success Manager about enabling the API in your Unify Tenant.

Once the API is enabled, your Living Security Client Success Manager and Field Engineer can help you determine the best technical path for interacting with the Unify API V1. Options include but are by no means limited to:

• Logstash OSS - The free and open-source version of Elastic’s Logstash utility can be easily configured to collect data from a variety of on-premise sources (files, syslog, etc), and push the data directly to the Unify API V1.

• Vendor Forwarders - Some on-premise products, including ZScaler and Splunk, can forward events via Syslog to a collector like Logstash. Other products, like ZScaler’s Cloud NSS feed, can be configured to push events directly to the Unify API V1 without an collector in between. Any forwarder that can conform with the API’s expectations and HTTP semantics may be used.

• Custom code - Since the Unify API V1 is a REST API, any modern programming language can be easily used to process data and push it to the API via HTTP. Examples will be provided upon request.

• Future SDK - while there is no Unify SDK currently, SDKs in a variety of languages may be made available in the future.

🔒 Authentication

The Unify API V1 utilizes bearer tokens for authentication. Tokens generated in the Unify platform are sensitive, should be stored in a secure vault (such as a password manager), and should never be shared with anyone. Additionally, the Unify platform never stores or logs the API Secrets in plain text.

Please see this article for instructions on how to generate a Unify API Token.

To authenticate to the Unify API V1, your API Token must be included in every request. The API token must be provided in the x-api-key Header, and structured as <api key>.<api secret>. Following the example above, you would provide your API key like so:

x-api-key: [api key].[api secret value]

🚪Endpoints

The following are Endpoints currently supported by the Unify API V1

📤 POST - /services/{Service ID}/streams/{Stream ID}/events

This endpoint supports ingestion of Events for a given Service and Stream. Services and Streams can be set up in the Unify Platform, and once they are set up Events may be pushed to Unify and associated with those Services and Streams.

Please work with your Client Success Manager and Field Engineer to determine how best to format the data you’re sending to Unify via this endpoint.

❓Request Structure

💬 cURL example:

curl -v -XPOST -H "content-type:application/json" -H "x-api-key:[api key].[api secret value]" "https://unify.api.livingsecurity.com/v1/services/aaaaaaaa-22c1-1111-bd9b-7ca5fa5938d8/streams/bbbbbbbb-35db-1111-888d-47337e3ebb0e/events" -d ‘[{"test":"test"}]’

📦 Request Body

The request body must be a valid JSON array with between 1 and 100 JSON objects. If more than 100 JSON objects are included, the Unify API V1 will respond with a 413 Content Too Large response code.

Because Unify is able to handle arbitrary JSON structures and convert/map those structures post-ingestion, the JSON objects in the JSON array can be in any structure provided that the structure is valid JSON and consistent across objects, and provided that a Unify Converter has been defined and associated with the relevant Service and Stream. Please talk to your Client Success Manager and Field Engineer about defining a Unify Converter.

* This endpoint does not currently support a strong/strict JSON schema, but will in the future.

Example request body:

[ {"field": "one", "field2": "two"}, {"field": "three", "field2": "four"}, {"field": "five", "field2": "six"}, {"field": "seven", "field2": "eight"} ]

The JSON response body is intended to be a convenient way to understand whether your request succeeded or failed, and may include hints as to why a failure occurred to help in debugging your integration with the API. However, the JSON response bodies are not meant to be used programmatically - for example, to detect a failure and retry a request. As indicated above, please use the HTTP response codes for this purpose.

{ "message": "OK", "statusCode": 200, "hint": null "converted": 100, "delivered": 100, }

CONTRACTOR
ELEVATED_ACCESS
EXECUTIVE
LEAVER
NEW_HIRE
PERFORMANCE_IMPROVEMENT
REMOTE_EMPLOYEE
SECURITY_TEAM
SENSITIVE_DATA_ACCESS
TENURED

curl -v -XPOST \
  -H "content-type:application/json" \
  -H "x-api-key:3mt9uvvcbbhk.y6Ue1fddPOsV3RhRgrqjJfrncHuH4uxF" \
  "https://unify.api.livingsecurity.com/v1/impact-modifiers" \
  -d @/path/to/body.json

{
  "alias": {
    "type": "EMAIL",
    "normalized": "foo@example.com"
  },
  "modifiers": [
    { "type": "EXECUTIVE", "action": "create" }
  ]
}

[
  {
    "alias": { "type": "EMAIL", "normalized": "foo@example.com" },
    "modifiers": [
      { "action": "create", "type": "EXECUTIVE" }
    ]
  },
  {
    "alias": { "type": "EMAIL", "normalized": "bar@example.com" },
    "modifiers": [
      { "action": "delete", "type": "CONTRACTOR" },
      { "action": "create", "type": "REMOTE_EMPLOYEE" },
      { "action": "create", "type": "ELEVATED_ACCESS" }
    ]
  }
]

{
  "message": "OK",
  "converted": 2,
  "delivered": 2,
  "statusCode": 200,
  "hint": null
}