Overview

This guide serves as a walkthrough for using Synqly APIs to integrate an application with a supported Provider. This guide will use curl to directly communicate with API endpoints, however, all operations described here can also be performed using one of our supported SDKs.

At a high-level, you will:

Create a Synqly Account for testing purposes.
Store a Credential set for authenticating with a Provider.
Create an Integration of a specific Provider type within the Account.
Use the Integration to send requests to a Provider.

Or, more specifically:

Create a Synqly Account for testing purposes.
Store a Splunk HTTP Event Collector (HEC) Token as a Synqly Credential.
Create a Splunk Integration.
Submit an event object to Splunk using the Integration.

Prerequisites

The steps described in this guide assume a pre-existing Synqly Organization. An Organization is the top-level organizational unit for a Synqly customer. If you do not have an Organization ID and Token, you can sign up through our Synqly Signup page.

Use the following command to export your Organization ID and Token as environment variables:

export SYNQLY_ORG_ID="<organization id>"
export SYNQLY_ORG_TOKEN="<organization token>"

You will need the authentication credentials of a Provider. If following this guide exactly, you will need a Splunk instance and a corresponding HTTP Event Collector (HEC) Token.

Sign up for a free trial of Splunk Cloud using Splunk's Create Your Account page.
Enable HTTP Event Collector and create a HEC Token using Splunk's Getting Data In guide.
Export your Splunk URL and HEC Token as environment variables.

export SPLUNK_URL="https://<your-id>.splunkcloud.com:8088/services/collector/event"
export HEC_TOKEN="<Splunk HTTP Collector Token>"

Step 1: Create A Test Account

Accounts in Synqly provide isolation between your customers and environments. Credential and Integrations objects must belong to a parent Account.

The following command will create an Account named test-account. The "contact" field is a required field for Account creation that is normally used as the default SMTP From address for an Account. This guide will not require any SMTP activity, so feel free to set "contact" to any email address.

curl -s --request POST \
     --header "Authorization: Bearer $SYNQLY_ORG_TOKEN" \
     --url "https://api.synqly.com/v1/accounts" \
     --header "content-type: application/json" \
     --header "accept: application/json" \
     --data '{
              "name":"test-account",
              "contact":"<your-email-address>"
              }'

The result should resemble the following:

{
  "result": {
    "account": {
      "name": "test-account",
      "created_at": "2023-09-28T18:41:11.72973Z",
      "updated_at": "2023-09-28T18:41:11.72973Z",
      "id": "412dbf85-c36d-4ac3-b239-c2efe81761cc"
    }
  }
}

Use the following command to export the Account id for later use:

export SYNQLY_ACCOUNT_ID=<account-id-from-output>

Step 2: Add Credentials

Now that an Account has been created, it is possible to create a Credential object for authenticating with the target Provider.

The following command will securely store your Splunk HEC token as a Synqly Credential object:

curl -s --request POST \
     --header "Authorization: Bearer $SYNQLY_ORG_TOKEN" \
     --url "https://api.synqly.com/v1/credentials/$SYNQLY_ACCOUNT_ID" \
     --header "content-type: application/json" \
     --header "accept: application/json" \
     --data '
            {
                "config": {
                    "type": "token",
                    "secret": "'$HEC_TOKEN'"
                }     
            }' | jq .

The result should resemble the following:

{
  "result": {
    "name": "splunk-hec",
    "created_at": "2023-09-28T19:32:16.773634Z",
    "updated_at": "2023-09-28T19:32:16.773634Z",
    "id": "295cee9b-73a1-41a4-9af1-f91c2b2d97d1",
    "account_id": "7629e5d4-e3e3-4f81-a192-47302ddcf500",
    "type": "token"
  }
}

Use the following command to export the Account id for later use:

export CREDENTIAL_ID="<credential-id-from-output>"

Note that once created, you cannot access the secret field through the Synqly API. The secret field of a Credential object is intentionally write-only.

Step 3: Connect to the Provider

We are now ready to create a Synqly Integration. This instantiates a connection between Synqly and the Provider. Once configured, you can use the Connector API to communicate with the Provider.

Continuing the example using Splunk, the following command will create a Splunk Integration.

curl -s --request POST \
        --header "Authorization: Bearer $SYNQLY_ORG_TOKEN" \
        --url "https://api.synqly.com/v1/integrations/$SYNQLY_ACCOUNT_ID" \
        --header "content-type: application/json" \
        --header "accept: application/json" \
        --data '
                {
                    "fullname": "splunk-integration-1",
                    "provider_config": {
                        "type": "siem_splunk",
                        "skip_tls_verify": true,
                        "hec_url": "'$SPLUNK_URL'",
                        "hec_credential": {
                            "type": "token_id",
                            "value": "'$CREDENTIAL_ID'"
                        }
                    }
                }' | jq .

This returns a response that includes an id and token needed to communicate with the Integration. The response should resemble the following:

{
  "result": {
    "integration": {
      "name": "splunk-integration",
      "created_at": "2024-01-08T19:41:40.939354Z",
      "updated_at": "2024-01-08T19:41:40.939354Z",
      "id": "51379956-2354-4c7a-a3bb-ea9651ed6402",
      "fullname": "splunk-integration",
      "refresh_token_id": "207e235e-d6c7-4a7a-a493-5ed9d57d214c",
      "account_id": "eecbd10f-efc4-4445-a94c-a5c24adfab09",
      "category": "siem",
      "provider_config": {
        "hec_credential": {
          "type": "token_id",
          "value": "<credential-id>"
        },
        "hec_url": "https://<splunk-url>/services/collector/event",
        "skip_tls_verify": true,
        "type": "siem_splunk"
      },
      "provider_fullname": "Splunk",
      "provider_type": "splunk",
    },
    "token": {
      "access": {
        "secret": "<access-token-value>",
        "expires": "2025-01-07T19:41:41Z",
        "permissions": {
          "role_binding": [
            "administrator"
          ],
          "resource_id": "51379956-2354-4c7a-a3bb-ea9651ed6402",
          "resource_type": "integration",
          "parent_id": "",
          "id": "",
          "organization_id": "",
          "member_id": ""
        },
      },
      "refresh": {
        "secret": "<refresh-token-value>",
        "expires": "2025-01-08T19:41:41Z",
        "permissions": {
          "role_binding": [
            "administrator"
          ],
          "resource_id": "51379956-2354-4c7a-a3bb-ea9651ed6402",
          "resource_type": "integration_refresh",
          "parent_id": "",
          "id": "",
          "organization_id": "",
          "member_id": ""
        },
      }
    }
  }
}

There's a lot returned here, but the things we need are the Integration id and its corresponding access token secret. Respectively, these fields are result.integration.id and result.token.access.secret.

Note that there are two tokens returned. The "access" token is used to make API calls, whereas the "refresh" token is used for rotating token credentials. This guide will only require the "access" token; to learn more about Synqly tokens in general, refer to Authentication.

Export both the Integration id and access token as environment variables using the following:

export SYNQLY_INTEGRATION_ID="<integration-id-from-response>"
export SYNQLY_INTEGRATION_TOKEN="<access-token-value-from-response>"

Step 4: Use the Integration

The Integration configuration is complete and we are ready to use the Connector API associated with it. You will need to use the specific API for the category of Integration created in Step 3.

The Splunk Integration configured above is part of the SIEM Events API.

To test it out, you can send an event to Splunk using the following:

curl -s --request POST \
        --header "Authorization: Bearer $SYNQLY_INTEGRATION_TOKEN" \
        --url "https://sandbox-api.synqly.com/v1/siem/events" \
        --header "content-type: application/json" \
        --header "accept: application/json" \
        --data '[{
                  "activity_id": 1,
                  "category_uid": 6,
                  "class_uid": 0,
                  "class_name": "API Activity",
                  "status_code": "X11",
                  "time": 1693955236,
                  "type_uid": 600301
                }]'

Once complete, you should be able to login to Splunk and see the event appear in the HTTP Collector created in Step 2.