Skip to main content

​
When to Use Headless Auth

For most use cases, we recommend using the Auth SDK. It’s quick to implement and automatically handles MFA and other edge cases. Use headless authentication only when you:
  • Have stored credentials - You own or already store the credentials required by the source.
  • Your source has no auth requirement - This integration method also works for sources that do not require user credentials at all.

​
Prerequisites

​
Integration Guide

1

Set up environment variables

Configure your Deck API credentials as environment variables. Both keys are available in your Dashboard..env
DECK_CLIENT_ID=your_client_id_here
DECK_CLIENT_SECRET=your_secret_here
2

Run the EnsureConnection Job

Call the EnsureConnection job with the stored credentials. This job runs asynchronously and returns results via webhook.
Connections stay open for 1 hour.
curl --request POST \
  --url https://sandbox.deck.co/api/v1/jobs/submit \
  --header 'x-deck-client-id: <your-client-id>' \
  --header 'x-deck-secret: <your-secret>' \
  --header 'Content-Type: application/json' \
  --data '{
    "job_code": "EnsureConnection",
    "input": {
      "source_guid": "<source-guid>",
      "username": "<username>",
      "password": "<password>"
    }
  }'
Available parameters on EnsureConnection
​
source_guid
string
required
The unique identifier of the source you want to connect to. See the Sources guide for more information.
​
username
string
required
Your user’s username or email for the source they’re connecting to. In Sandbox, any value can be used as authentication is simulated.
​
password
string
required
Your user’s password for the source they’re connecting to. In Sandbox, any value can be used as authentication is simulated.
​
external_id
string
Customer identifier from your system. Link a Deck connection to your customer ID to look up connections by your external identifier in the Dashboard.
​
webhook_url
string
Custom webhook URL to receive events for this connection. Overrides the default webhook URL configured in your Dashboard.
​
target_url
string
Target URL for the connection. Used to specify a specific endpoint or page to navigate to during authentication. For example YouTube may be your source, and the Target URL would be a specific video.
​
account_id
string
Used when a set of credentials has multiple accounts attached to it and you want to target a specific account.
3

Receive Access Token via Webhook

Once authentication is successful, your webhook receives the access token.Success Webhook Payload:
{
  "job_guid": "b3ab44de-f722-4685-ab3a-b27b369e859b",
  "output": {
    "access_token": "access-sandbox-34343434-bcbc-34bc-34bc-343434343434"
  },
  "webhook_type": "Job",
  "webhook_code": "EnsureConnection",
  "environment": "Sandbox"
}
4

Use Access Tokens to Run Jobs

Use the access token to run jobs on behalf of the user. Jobs can read data (e.g., fetch documents, invoices) or write data (e.g., submit orders, update records).See the Jobs guide for more information.