# 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](https://docs.synqly.com/docs/sdk). At a high-level, you will: 1. Create a Synqly `Account` for testing purposes. 2. Store a `Credential` set for authenticating with a Provider. 3. Create an `Integration` of a specific Provider type within the `Account`. 4. Use the `Integration` to send requests to a Provider. Or, more specifically: 1. Create a Synqly `Account` for testing purposes. 2. Store a Splunk HTTP Event Collector (HEC) Token as a Synqly `Credential`. 3. Create a Splunk `Integration`. 4. 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](https://app.synqly.com/auth/signup) page. Use the following command to export your Organization ID and Token as environment variables: ```bash export SYNQLY_ORG_ID="" export SYNQLY_ORG_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. 1. Sign up for a free trial of Splunk Cloud using Splunk's [Create Your Account](https://www.splunk.com/en_us/sign-up.html) page. 2. Enable HTTP Event Collector and create a HEC Token using Splunk's [Getting Data In](https://docs.splunk.com/Documentation/Splunk/9.1.1/Data/UsetheHTTPEventCollector) guide. 3. Export your Splunk URL and HEC Token as environment variables. ```bash export SPLUNK_URL="https://.splunkcloud.com:8088/services/collector/event" export HEC_TOKEN="" ``` ## Step 1: Create A Test Account `Account`s 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. ```bash 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":"" }' ``` The result should resemble the following: ```json { "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: ```bash export SYNQLY_ACCOUNT_ID= ``` ## 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: ```bash 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: ```json { "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: ```bash export CREDENTIAL_ID="" ``` 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](https://docs.synqly.com/reference/integrations_create). 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`. ```bash 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: ```json { "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": "" }, "hec_url": "https:///services/collector/event", "skip_tls_verify": true, "type": "siem_splunk" }, "provider_fullname": "Splunk", "provider_type": "splunk", }, "token": { "access": { "secret": "", "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": "", "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](https://docs.synqly.com/reference/api-authentication). Export both the `Integration` id and access token as environment variables using the following: ```bash export SYNQLY_INTEGRATION_ID="" export SYNQLY_INTEGRATION_TOKEN="" ``` # 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](https://docs.synqly.com/reference/siem_post_events). To test it out, you can send an event to Splunk using the following: ```bash 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. To search for the event in Splunk, navigate to "Search & Reporting" and search for `sourcetype=httpevent`.