> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deck.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Headless Authentication

> Authenticate users programmatically without user interaction.

## 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

* Your Deck API credentials. [Quickstart Guide](/guides/guides/quickstart)
* A webhook endpoint configured and ready to receive webhooks. [Webhooks Guide](/guides/webhooks/webhooks)
* Source GUIDs for the data sources you want to connect to. [Sources Guide](/guides/guides/sources)

## Integration Guide

<Steps>
  <Step title="Set up environment variables">
    Configure your Deck API credentials as environment variables. Both keys are available in your [Dashboard](https://dashboard.deck.co).

    **.env**

    ```bash theme={null}
    DECK_CLIENT_ID=your_client_id_here
    DECK_CLIENT_SECRET=your_secret_here
    ```
  </Step>

  <Step title="Run the EnsureConnection Job">
    Call the `EnsureConnection` job with the stored credentials. This job runs asynchronously and returns results via webhook.

    <Info>Connections stay open for 10 minutes without receiving another job.</Info>

    ```bash theme={null}
    curl --request POST \
      --url https://live.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`**

    <ParamField path="source_guid" type="string" required>
      The unique identifier of the source you want to connect to. See the [Sources guide](/guides/guides/sources) for more information.
    </ParamField>

    <ParamField path="username" type="string">
      Your user's username or email for the source they're connecting to.
    </ParamField>

    <ParamField path="password" type="string">
      Your user's password for the source they're connecting to.
    </ParamField>

    <ParamField path="external_id" type="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](https://dashboard.deck.co).
    </ParamField>

    <ParamField path="access_token" type="string">
      An existing access token from a previous connection. Use this to establish a connection and run jobs in subsequent sessions without the user present.
    </ParamField>

    <ParamField path="webhook_url" type="string">
      Custom webhook URL to receive events for this connection. Overrides the default webhook URL configured in your Dashboard.
    </ParamField>

    <ParamField path="account_id" type="string">
      Used when a set of credentials has multiple accounts attached to it and you want to target a specific account.
    </ParamField>
  </Step>

  <Step title="Receive Access Token via Webhook">
    Once authentication is successful, your webhook receives the access token.

    **Success Webhook Payload:**

    ```json highlight={4} theme={null}
    {
      "job_guid": "b3ab44de-f722-4685-ab3a-b27b369e859b",
      "output": {
        "access_token": "access-production-34343434-bcbc-34bc-34bc-343434343434"
      },
      "webhook_type": "Job",
      "webhook_code": "EnsureConnection",
      "environment": "Production"
    }
    ```
  </Step>

  <Step title="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](/guides/guides/jobs) for more information.
  </Step>
</Steps>