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. For connections that don’t require auth, you can pass an empty string for the username and password.
Connections stay open for 1 hour.
curl --location 'https://sandbox.deck.co/api/v1/jobs/submit' \
  --header 'x-deck-client-id: <api-key>' \
  --header 'x-deck-secret: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "job_code": "EnsureConnection",
    "input": {
      "username": "user@example.com",
      "password": "user_password",
      "source_guid": "14ba5f04-2be4-4ccb-870c-1944ad06da42"
    }
  }'
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.
⌘I