API connections let another system run your SmartSYNC flows using a standard OAuth2 access token and a single REST request. This is now the recommended way to run flows from outside SmartSYNC; the original real-time API still works and remains available as a backup.
API connections are available once API Access is switched on for your account.
The real-time API has its own setting, Real-time API (key and secret), under the same section. If you already had API Access on, it stays on so existing integrations keep working. Switch it off if nothing uses it any more; the two settings are independent.
You also need the flow, or flows, you want to run. A flow does not need to be switched on to be run through the API. If you want to send data into the flow, its first step must be the Webhook connector with the Incoming webhook event.
Each API connection is a named set of credentials that can run only the flows you choose. Create a separate connection for each system or partner, so you can see which one ran a flow and switch one off without affecting the others.
The client secret is shown only once. If you lose it, rotate the secret (see Manage your connections) and update the system that uses it.
If you are setting this up for a partner, send them the client ID and secret separately, using a secure method, together with the flow IDs they may run. A flow's ID is shown in the flow list and in the address bar when you open the flow.
Your system exchanges the client ID and secret for an access token using the standard OAuth2 client credentials grant. Tokens last one hour; request a new one when it expires.
Request
POST https://<your SmartSYNC server>/api/v1/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=<client ID>&client_secret=<client secret>You can send the client ID and secret as HTTP Basic authentication instead of in the body. A JSON body with the same three fields is also accepted.
Response
{
"access_token": "eyJhbGciOi...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "flows:run"
}If the request is refused
Status | error | Meaning |
|---|---|---|
400 | invalid_request | A field is missing or the body could not be read |
400 | unsupported_grant_type | grant_type is not client_credentials |
401 | invalid_client | The client ID or secret is wrong, the connection is switched off, or API Access is off for the account |
429 | too_many_requests | Too many failed attempts; wait a few minutes and try again |
Example with curl
curl -X POST https://<your SmartSYNC server>/api/v1/token \
-u "<client ID>:<client secret>" \
-d grant_type=client_credentialsSend one request per run, with the access token in the Authorization header. The flow runs straight away and the response arrives when it has finished, so allow up to 60 seconds.
Request
POST https://<your SmartSYNC server>/api/v1/flows/<flow ID>/runs
Authorization: Bearer <access token>
Content-Type: application/json
{"email": "jo@example.org", "amount": 25}The body is optional. Send one only if the flow starts with the Webhook connector's Incoming webhook event; the flow's later steps can then use the fields you send, exactly as they would for a webhook.
Successful run
{
"success": true,
"run_id": 123456,
"outputs": [ ... ]
}outputs holds whatever the flow returns. Quote the run_id if you contact support about a run.
Run that started but failed
{
"success": false,
"run_id": 123457,
"error": { "code": 123, "msg": "A description of what went wrong" }
}Status codes
Status | Meaning | What to do |
|---|---|---|
200 | The flow ran successfully | Read |
400 | The body is not valid JSON | Fix the body and try again |
401 | The token is missing, wrong or expired, or the connection has been switched off or its secret rotated | Get a new token; if that fails, check the connection in SmartSYNC |
404 | Flow not found: the ID is wrong, or the flow is not ticked for this connection | Check the flow ID and the connection's flow list |
422 | The flow ran but failed | Read |
500 | Something unexpected went wrong on the server | Try again later; contact support if it continues |
Every response is JSON. A 401 response also carries a WWW-Authenticate header, as the OAuth2 standard requires.
Example with curl
curl -X POST https://<your SmartSYNC server>/api/v1/flows/<flow ID>/runs \
-H "Authorization: Bearer <access token>" \
-H "Content-Type: application/json" \
-d '{"email": "jo@example.org", "amount": 25}'The API connections list shows each connection's name, client ID, the flows it may run and when it was last used.
To | Do this | Effect |
|---|---|---|
Change the flows a connection may run | Select Edit, change the ticked flows, save | Takes effect on the next request |
Pause a connection | Switch off Enabled | New tokens are refused and existing tokens stop working; switch it back on to resume |
Replace a lost or exposed secret | Select Rotate secret and copy the new secret | The old secret and every token issued with it stop working straight away |
Remove a connection | Select Delete | The connection and its tokens stop working permanently |
Switching off API connections (OAuth2) stops every API connection until it is switched on again; the real-time API is not affected. Switching off API Access stops both methods.
API connections are not moved if your account is moved to another SmartSYNC server. Create them again on the new server and send the new credentials to whoever uses them.
Team members with read-only access can see the list but cannot change it.
The original real-time API still works, and existing integrations that use it do not need to change. It uses the account's API key and secret with a signed request rather than OAuth2. For new integrations we recommend API connections, because each one can be limited to chosen flows, identified in the logs and switched off on its own.
The backup method is described in SmartSYNC real-time API: security and requests.