SmartSYNC API connections: run a flow with OAuth2 and REST

SmartSYNC API connections: run a flow with OAuth2 and REST

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.

Before you start

API connections are available once API Access is switched on for your account.

  1. Sign in to SmartSYNC and open Admin, then Account.
  2. Under API Access, tick Enable?.
  3. Tick API connections (OAuth2) and save.
  4. The API connections section appears below it.

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.

Create an API connection

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.

  1. Go to Admin, then Account, then API connections.
  2. Select New connection.
  3. Enter a name that says who will use it, for example "Events partner".
  4. Tick the flows this connection may run. You can change this later.
  5. Select Save.
  6. Copy the Client ID and Client secret and store them somewhere safe, such as a password manager.

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.

Get an access token

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_credentials

Run a flow

Send 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 outputs

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 error.msg and the run in the SmartSYNC logs

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}'

Manage your connections

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.

Keeping your connection secure

  • Create one connection per system or partner, and tick only the flows it needs.
  • Keep the client secret on a server. Never put it in a web page, a mobile app or a public code repository.
  • Send credentials to a partner through a secure channel, never in the same email as the client ID.
  • Rotate the secret when someone who knew it leaves, or if you think it has been exposed.
  • Check Last used from time to time, and delete connections you no longer need.

The real-time API: the backup method

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.