API Authentication
The Syntropy API uses different methods of authentication. The main method of authentication is API Access Tokens (recommended), to authenticate requests. You can view and manage your API Access Tokens in the Syntropy Dashboard. In such a case, authentication to the API is performed via Bearer Authentication.
API Access Tokens
Syntropy authenticates your API requests using API Access Tokens. If you don’t include your API Access Token when making an API request or use an incorrect or outdated one, Syntropy returns an error. Every account may have multiple access tokens with different permissions for different purposes.
When creating a new API Access Token you can set its validity period by setting the expiry date. You can also set permissions which specify which scopes it has access to.
Keeping your API Access Tokens safe
Your API Access Tokens can be used to make any API call on behalf of your account, such as creating connections or deleting services. Treat your API Access Token as you would any other password. Grant access only to those who need it. Ensure it is kept out of any version control system you may be using. Control access to your key using a password manager or secrets management service.
Deleting API Access Tokens
If an API Access Token is compromised, delete the token from the Dashboard to block it and generate a new one. When deleting an API Access Token, it’s deleted immediately and thus any API calls using that token will be blocked and have no access to your account’s resources. The new token can also be used immediately.
API Versioning
When backwards-incompatible changes are made to the API, a new, dated version is released. Read our API upgrades guide to see our API change-log and to learn more about backwards compatibility.
API Upgrades
Your API version controls the API and web-hook behavior you see (e.g., what properties you see in responses, what parameters you’re permitted to send in requests, etc.). When we change the API in a backwards-incompatible way, we release a new dated version, but to avoid breaking your code, we don’t change your version until you’re ready to upgrade.
Backwards-compatible changes
Syntropy considers the following changes to be backwards-compatible:
* Adding new API resources.
* Adding new optional request parameters to existing API methods.
* Adding new properties to existing API responses.
* Changing the order of properties in existing API responses.
* Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.
* Adding new event types. Your web-hook listener should gracefully handle unfamiliar event types.
Pagination
All top-level API resources have support for bulk fetches via "list" API methods. For instance, you can list Agents, list Connections as well manage your agent tokens and access tokens . These list API methods share a common structure, taking at least these three parameters: skip, take, order.
Syntropy utilizes cursor-based pagination via the skip and take parameters. Both parameters take an existing object ID value and return objects based on the passed order parameter.
The take parameter returns objects listed before the named object. The skip parameter returns objects listed after the named object. These parameters are mutually exclusive - only one of the skip and take may be used.