# 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.


```go
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:


```bash
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](https://www.rfc-editor.org/rfc/rfc6749#section-1.4) 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](https://www.rfc-editor.org/rfc/rfc6749#section-1.5) 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](https://app.synqly.com).

## 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.