Skip to content
/
Authentication

Overview

Every request to the Synqly API must be authenticated by an access token with enough permissions to perform the target operation.

Synqly tokens fall into one of two scopes:

  • Organization: Organization access tokens are used to authenticate requests to "Management" APIs, such as v1/accounts and v1/integrations.

  • Integration: Integration access tokens are used to authenticate requests to "Connectors" APIs. Each Integration token is unique to a single Integration, which is an instantiation of a connection to a target Provider.

In order to use a token with a Synqly API request, it must be used as a Bearer token in the request Authorization header. That is, you must include the header Authorization: Bearer <token access secret> in each request.

Synqly SDK

When using Synqly SDKs, a token may be provided when first initializing an SDK client. The following example demonstrates initializing a management client with an Organization access token.

client := mgmtClient.NewClient(
    mgmtClient.WithAuthToken(synqlyOrgToken),
)

Direct HTTP

When communicating with Synqly APIs via Direct HTTP, a token must be included with every request in the format:

Authorization: Bearer <SYNQLY_TOKEN>

An full API call will resemble the following:

export SYNQLY_ORG_TOKEN=<insert organization token>
curl --request GET \
     --url https://api.synqly.com/v1/accounts \
     --header 'accept: application/json' \
     --header "Authorization: Bearer $SYNQLY_ORG_TOKEN"

Token Format

Every Synqly token is initially created as a TokenPair, containing both an access token, and a refresh token.

Synqly access tokens fill the role of an OAuth 2.0 Access Token for Synqly APIs. The access token is granted permission to call Synqly APIs, and will be the value you use to authenticate most requests.

Synqly refresh tokens fill the role of an OAuth 2.0 Refresh Token for Synqly APIs. The refresh token acts as a dedicated rotation key, and should only be used when refreshing or resetting an access token.

Token Scopes

Every token belongs to one of the following scopes. Token scopes do not overlap. Organization access tokens are used exclusively with "Management" APIs. Integration access tokens are used exclusively with "Connector" APIs.

Organization Tokens

Organization access tokens are used to perform management operations such as:

  • Managing Member objects within an Organization
  • Managing Account objects objects within an Organization
  • Managing Integration objects within an Account

Every API endpoint listed under the "Management" API spec requires an Organization access token.

If you need a new Organization access token, you can generate it through the Synqly UI.

Integration Tokens

Integration tokens are used to interact with a target Integration, usually within the context of sending or retrieving data.

Every API endpoint listed under the "Engine" API spec requires an Integration token.

Integration tokens are created and returned when an Integration is first initialized.

Previous page
Next page