Auth Component

The v2 Auth Component is in preview. APIs and component props may change before release.

The Auth Component is a pre-built React component that collects end-user credentials, stores them in the Credential Vault, and creates a Credential. Credentials never touch your systems. It handles source selection, username/password capture, interactions (MFA, security questions), and error states out of the box.

Want full customization and control over the UX? See Building your auth flow to build your own using the API directly.

How it works

Your server creates a session token via POST /v2/token
Your frontend mounts <DeckAuthComponent /> with the token and all configuration
The component renders a secure UI where the user selects a source and enters credentials
Credentials go from the component directly to the Deck API and into the Credential Vault. They never touch your page
On success, the component returns the new Credential ID via onSuccess

Restrictions

Only supports auth_method: username_password
Does not support chaining to tasks with inputs
Does not support source_fields on the credential

Installation

npm install @deck/auth

import { DeckAuthComponent } from '@deck/auth';

React 18+ is a peer dependency.

Quick example

Create a session token on your server:

Server

const response = await fetch('https://api.deck.co/v2/token', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
  },
});

const { token } = await response.json();

Mount the component in your React app:

Client

<DeckAuthComponent
  token={token}
  sourceId="src_abc123"
  externalId="user_12345"
  taskId="task_x9y8z7..."
  onSuccess={({ credentialId, externalId, taskRunId, verified }) => {
    console.log('Credential created:', credentialId);
  }}
  onError={({ type, code, message }) => {
    console.error('Auth failed:', code, message);
  }}
  onClose={() => {
    // User dismissed the component. Unmount, navigate, etc.
  }}
/>

Session token

Every auth component session starts with a server-side token. The token is authentication only. It proves the request came from your backend. All configuration (sourceId, appearance, etc.) is passed on the component, not the token.

`POST /v2/token`

Creates a session token for the Auth Component. Authentication: Authorization: Bearer sk_live_... Request body: None Response (201):

{
  "id": "tok_abc123...",
  "object": "token",
  "token": "tk_abc123...",
  "expires_at": "2026-04-10T12:30:00Z",
  "created_at": "2026-04-10T12:00:00Z",
  "request_id": "req_xyz789"
}

Field	Type	Description
`id`	string	Token identifier, prefixed `tok_`
`object`	string	Always `token`
`token`	string	The token value to pass to the component, prefixed `tk_`
`expires_at`	ISO 8601	30 minutes from creation
`created_at`	ISO 8601	Creation timestamp
`request_id`	string	Request ID for support

Token lifecycle

Tokens expire 30 minutes after creation
Expired tokens return a clear error to onError

Component props

Prop	Type	Description
`token`	`string`	Required. Session token from `POST /v2/token`.
`sourceId`	`string \| string[]`	Pre-select a single source (skips picker) or filter to multiple.
`credentialId`	`string`	If provided, enters Update Mode. Re-collects credentials for an existing credential.
`externalId`	`string`	Your user ID. Passed back in `onSuccess` and persisted on the credential.
`taskId`	`string`	If provided, fires a verification task run after credential creation/update.
`appearance`	`AppearanceConfig`	Full theming control. See Appearance.
`taskRunView`	`"status" \| "live"`	How the task run is displayed while executing. Defaults to `"status"`.
`onSuccess`	`(data) => void`	Required. Called when credential creation/update succeeds.
`onError`	`(data) => void`	Called on failure. See Error handling.
`onClose`	`() => void`	If provided, shows a close button. Called when user clicks it. If omitted, no close button is rendered.

The component does not own its lifecycle. Your app does. When onClose fires, you decide what happens (unmount, navigate, show a confirmation, etc.).

Callbacks

`onSuccess`

onSuccess: (data: {
  credentialId: string;
  externalId: string | null;
  taskRunId: string | null;
  verified: boolean | null;
}) => void;

Field	Type	Description
`credentialId`	`string`	The created or updated credential
`externalId`	`string \| null`	Your external ID, if provided
`taskRunId`	`string \| null`	Verification task run ID. `null` if no `taskId` was passed
`verified`	`boolean \| null`	`true` if run succeeded, `false` if run failed, `null` if no `taskId` was passed

`onError`

onError: (data: {
  type: string;
  code: string;
  message: string;
}) => void;

type is the error category. code is the machine-readable identifier. message is human-readable and may change. Switch on type and code, not message. See Error handling for all error codes.

`onClose`

onClose: () => void;

If onClose is provided, the component renders a close button. When clicked, onClose fires and you handle the teardown. If onClose is omitted, no close button is rendered. Pressing Escape also fires onClose if provided. If a task run is in progress when the user closes the component, the task run continues running in the background. To cancel it, use the cancel endpoint from your onClose handler.

Source selection

The sourceId prop controls what the user sees before credential capture.

`sourceId`	Behavior
Not provided	Full source search. User searches across all sources in your organization.
Single ID (`"src_abc123"`)	Skips source selection. Goes straight to credential capture.
Array (`["src_abc", "src_def"]`)	Filtered selection. User picks from the provided sources in your organization.

Update mode

Pass a credentialId to re-collect credentials for an existing credential instead of creating a new one.

`credentialId`	`sourceId`	Behavior
absent	absent	Create mode. Full source search.
absent	present	Create mode. Skip/filter source selection.
present	ignored	Update mode. Skip source selection, patch existing credential.

<DeckAuthComponent
  token={token}
  credentialId="cred_existing_456"
  externalId="user_12345"
  onSuccess={({ credentialId, externalId }) => {
    console.log('Credentials updated for:', credentialId);
  }}
/>

Task linking

Pass a taskId to verify credentials immediately after creation. The component fires a task run using the new credential, and the task run view stays visible while it executes.

`taskId`	Run outcome	Credential status	`onSuccess` payload
absent	n/a	`unverified`	`{ credentialId, externalId, taskRunId: null, verified: null }`
present	run succeeds	`verified`	`{ credentialId, externalId, taskRunId, verified: true }`
present	run fails	`verified`	`{ credentialId, externalId, taskRunId, verified: false }`

The credential becomes verified as long as the agent authenticates successfully, even if the task run itself fails. A failed run does not delete or invalidate the credential.

`taskRunView`

With taskId present, the task run view is shown while the run executes:

"status": spinner with status text (e.g., “Connecting…”, “Verifying credentials…”)
"live": live view of the task run

Without taskId, no task run view is shown.

Appearance

Customize the component’s look via the appearance prop.

<DeckAuthComponent
  token={token}
  appearance={{
    theme: 'dark',
    variables: {
      colorPrimary: '#0066FF',
      borderRadius: 8,
    },
    layout: {
      logoUrl: 'https://example.com/logo.svg',
    },
  }}
  onSuccess={handleSuccess}
/>

Theme

Value	Description
`"default"`	Light theme with neutral styling
`"dark"`	Dark theme

Variables

Variable	Description
`colorPrimary`	Primary button and accent color
`colorBackground`	Card background
`colorForeground`	Main text color
`colorPrimaryForeground`	Text on primary buttons
`colorNeutral`	Neutral accent
`colorDanger`	Error states
`colorSuccess`	Success states
`colorMuted`	Muted backgrounds (hover, etc.)
`colorMutedForeground`	Secondary text
`colorBorder`	Border color
`colorInput`	Input border color
`colorRing`	Focus ring color
`fontFamily`	Font stack
`borderRadius`	Border radius in pixels (e.g., `8`)
`shadow`	Shadow token for card/elevated surfaces

Layout

Variable	Description
`logoUrl`	Logo shown in the card header (your logo, not Deck’s)
`logoPlacement`	`"top"` or `"left"`

Interactions

Sources may require additional input mid-flow: an MFA code, a security question, an account selection. The component handles these automatically as interactions: a generic pause-and-prompt primitive. When an interaction is required:

The component transitions to an interaction step and renders the fields from the source’s response
The user fills in the fields and submits
The source validates. On accept, the flow continues
Some sources require multiple sequential interactions (e.g., MFA code then a security question)

The component does not enforce its own interaction timeout. Timeout windows are set by the source and handled by the backend. The user cannot go back to credential entry from an interaction step (credentials have already been created). See Interactions for more on how Deck models interactions.

Error handling

All errors surface through onError with a uniform { type, code, message } shape.

Token errors

Type	Code	Description
`request`	`token_invalid`	Invalid or expired token

Credential errors

Type	Code	Description
`auth`	`auth_invalid`	Credentials rejected by the source
`auth`	`auth_method_not_supported`	Source does not support the attempted auth method
`auth`	`password_reset_required`	Source is forcing a password reset
`auth`	`account_locked`	Account is locked at the source
`request`	`credential_not_found`	Update mode: credentialId does not exist
`request`	`credential_deleted`	Update mode: credential has been deleted

Source errors

Type	Code	Description
`request`	`source_not_found`	The sourceId does not exist
`source`	`source_not_available`	Source is temporarily unreachable
`source`	`source_error`	Source returned an unexpected failure

Interaction errors

Type	Code	Description
`interaction`	`interaction_timeout`	Interaction window expired (source-defined)
`request`	`interaction_input_invalid`	Submitted input didn’t match the declared field schema

Error behavior

Token errors (token_invalid) terminate the session. Create a new token and remount.
Credential errors (auth_invalid, account_locked, etc.) terminate the session.
Interaction errors (interaction_timeout) terminate the session. Wrong user input is not an error, the source emits another prompt and the user retries in-place.

Get Started

Guides

Development

Platform

Migration Guides

How it works

Restrictions

Installation

Quick example

Session token

`POST /v2/token`

Token lifecycle

Component props

Callbacks

`onSuccess`

`onError`

`onClose`

Source selection

Update mode

Task linking

`taskRunView`

Appearance

Theme

Variables

Layout

Interactions

Error handling

Token errors

Credential errors

Source errors

Interaction errors

Error behavior

Get Started

Guides

Development

Platform

Migration Guides

​How it works

​Restrictions

​Installation

​Quick example

​Session token

​POST /v2/token

​Token lifecycle

​Component props

​Callbacks

​onSuccess

​onError

​onClose

​Source selection

​Update mode

​Task linking

​taskRunView

​Appearance

​Theme

​Variables

​Layout

​Interactions

​Error handling

​Token errors

​Credential errors

​Source errors

​Interaction errors

​Error behavior

How it works

Restrictions

Installation

Quick example

Session token

`POST /v2/token`

Token lifecycle

Component props

Callbacks

`onSuccess`

`onError`

`onClose`

Source selection

Update mode

Task linking

`taskRunView`

Appearance

Theme

Variables

Layout

Interactions

Error handling

Token errors

Credential errors

Source errors

Interaction errors

Error behavior