Skip to main content

​
When to Build a Custom UI

For most use cases, we recommend using the Auth SDK. It’s quick to implement and automatically handles MFA and other edge cases. Build a custom authentication UI only when you:
  • Need full UI control - Your design requires a specific authentication experience that doesn’t fit the SDK’s UI
  • Have existing auth flows - You want to integrate Deck into an existing authentication system

​
Prerequisites

​
Integration Guide

1

Set up environment variables

Configure your Deck API credentials as environment variables. These are required to generate SDK tokens and must never be exposed in frontend code. Both keys are available in your Dashboard..env
DECK_CLIENT_ID=your_client_id_here
DECK_CLIENT_SECRET=your_secret_here
2

Build Credential Collection Form

Create a form to collect user credentials. Most sources require username and password, but requirements vary by provider.
function CredentialForm({ onSubmit, isLoading }) {
  const [username, setUsername] = useState('');
  const [password, setPassword] = useState('');

  const handleSubmit = (e) => {
    e.preventDefault();
    onSubmit({ username, password });
  };

  return (
    <form onSubmit={handleSubmit}>
      <div>
        <label>Username or Email</label>
        <input
          type="text"
          value={username}
          onChange={(e) => setUsername(e.target.value)}
          required
        />
      </div>
      <div>
        <label>Password</label>
        <input
          type="password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          required
        />
      </div>
      <button type="submit" disabled={isLoading}>
        {isLoading ? 'Connecting...' : 'Connect Account'}
      </button>
    </form>
  );
}
3

Run the EnsureConnection Job

When the user submits credentials, call the EnsureConnection job from your server-side code. You will need to pass both the user’s credentials as well as the source you want to connect to. This job runs asynchronously and returns results via webhook.
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"
    }
  }'
4

Handle MFA Challenges (If Required)

If the source or user’s preferences requires MFA, your webhook will receive an MFA challenge. Display the appropriate UI to collect the MFA answer and submit it.Collect MFA Answer from User:
function MfaForm({ message, onSubmit, isLoading }) {
  const [answer, setAnswer] = useState('');

  return (
    <form onSubmit={(e) => {
      e.preventDefault();
      onSubmit(answer);
    }}>
      <label>{message}</label>
      <input
        type="text"
        value={answer}
        onChange={(e) => setAnswer(e.target.value)}
        placeholder="Enter code"
        required
      />
      <button type="submit" disabled={isLoading}>
        Verify
      </button>
    </form>
  );
}
Submit MFA Answer:
curl --location 'https://sandbox.deck.co/api/v1/jobs/mfa/answer' \
  --header 'x-deck-client-id: <api-key>' \
  --header 'x-deck-secret: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "job_guid": "b3ab44de-f722-4685-ab3a-b27b369e859b",
    "answer": "123456"
  }'
5

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-xyz789..."
  },
  "webhook_type": "Job",
  "webhook_code": "EnsureConnection",
  "environment": "Sandbox"
}
6

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).Job results are also delivered via webhook. See the Jobs guide for more information.
⌘I