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 asv1/accounts
andv1/integrations
.Integration
:Integration
access tokens are used to authenticate requests to "Connectors" APIs. Each Integration token is unique to a singleIntegration
, 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 anOrganization
- Managing
Account
objects objects within anOrganization
- Managing
Integration
objects within anAccount
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.