external_id when creating connections to tie multiple connections back to the same user in your system, so you can query all of a user’s connections without maintaining a separate mapping.
How connections fit in
A connection sits between a source and a task run. It gives the task run an authenticated browser session to work with. Once the connection status isconnected, you can run any of the source’s associated tasks against it.
Opening a connection
Pass credentials through the API, and Deck authenticates the user in the background. The API responds immediately withconnecting status while authentication proceeds asynchronously. Listen for connection.connected or connection.interaction_required events to know when the connection is ready, or poll GET /v2/connections/{connection_id} until the status changes.
Auth methods
| Method | Description |
|---|---|
username_password | Standard username and password |
google_sso | Google single sign-on |
none | No credentials needed (public sources) |
Connection statuses
| Status | Meaning |
|---|---|
connecting | Deck is authenticating the user (async, transitions automatically) |
connected | Session is active and ready for task execution |
interaction_required | The source is asking for verification (MFA, security question) |
invalid | The credentials were rejected by the source |
disconnected | The browser session was closed |
terminated | You closed the connection and credentials were permanently deleted |
invalid when the source rejects the provided credentials. This can happen on the initial login attempt or when previously valid credentials expire or are changed on the source. An invalid connection cannot run tasks. To retry, create a new connection with updated credentials.
Connections become disconnected after a period of inactivity or if the session drops. A disconnected connection can’t run tasks, but you can reopen it using the same connection ID.
A terminated connection is permanent. When you terminate a connection, Deck deletes the credentials from the vault and can no longer authenticate on behalf of that user. The connection object and its task runs are still queryable, but no new tasks can be executed.
Interactions
When a source requires MFA or other verification, the connection pauses withinteraction_required status. Collect the input from your user and submit it to resume. See Handling interactions for details.