Concepts
Identifiers and credentials
The two credentials and four ids you'll handle, and which one history follows.
Two credentials
| Credential | You get it from | You use it for |
|---|---|---|
| Developer session | Signing in to the console | The console: applications, connections, your profile |
| Connection access token | POST /v1/oauth/token | Executions for one connection |
The session is yours as a developer and isn't part of the API you integrate. The token belongs to one connection and goes on every execution request.
Tokens are long-lived and don't refresh, so a stored token works until it's revoked. Treat it like a password.
Issuing a new token for the same connection revokes the previous one, and POST /v1/oauth/revoke revokes one on
demand.
Four ids
| Id | Where it appears | What it identifies |
|---|---|---|
| Application id | client_id on the auth link; the path of the execution routes | Your OAuth client |
user_id | The token response; userId on a connection | The person, within your application |
connection_id | The token response | One website account belonging to that person |
| Execution id | The execution routes | One run |
A person can hold several connections, one per website. Store connections keyed by connection_id and group
them by user_id.
History follows the connection
GET /v1/applications/{id}/executions lists the runs of the connection the token belongs to. The history
belongs to the connection, not the token, so a user who reconnects keeps their history.
Ownership is checked everywhere
Every route checks that the application in the path, the token, and any nested id belong together. A mismatch returns not found rather than forbidden, so an id you don't own reveals nothing.
Next steps
Connections and authorization shows how a connection is created and what happens to it over its life.