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

# Verify credentials

> Sign in as a separate task to confirm credentials work before running other tasks.

A credential starts as `unverified` and becomes `verified` the first time a task run authenticates with it. If that first run is a data task you run later, the user may not be around to fix a wrong password or answer an MFA prompt.

This guide moves sign-in into its own task. Run it right after the user enters their credentials. The agent signs in and stops at the account view. If the source asks for an MFA code or a security question, the run pauses with an [interaction](/guides/interactions) for the user to answer.

Verifying credentials as a separate task has a few benefits:

* **A quick finish.** The task only signs in, so it usually finishes quickly. The user can leave sooner, you can wrap up the experience in your app, and the rest of your tasks run in the background.
* **The user is still there.** If the source rejects the credentials or asks for an MFA code, the user can fix or answer it right away.
* **Clear status.** The run's result tells you whether the credential works, separate from any data task.

## Prerequisites

This guide assumes you have an agent and a source; the [Quickstart](/guides/quickstart) covers those steps. To collect credentials, use the [Auth Component](/components/auth) or [build your own auth flow](/guides/building-auth-ui).

## Create the task

The task takes no input and returns `login_status`. It returns metadata only, so leave storage off. See [Tasks](/concepts/tasks) for guidance on writing prompts.

Use this prompt:

```text Prompt theme={null}
Sign in to verify credentials and continue through any additional verification steps until you reach the authenticated account view.
```

Or create the task through the API:

```bash Request theme={null}
curl -X POST https://api.deck.co/v2/tasks \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Verify credentials",
    "agent_id": "agt_a1b2c3d4...",
    "prompt": "Sign in to verify credentials and continue through any additional verification steps until you reach the authenticated account view.",
    "input_schema": {
      "type": "object",
      "properties": {}
    },
    "output_schema": {
      "type": "object",
      "required": ["login_status"],
      "properties": {
        "login_status": {
          "type": "boolean",
          "description": "Returns true if login is successful."
        }
      }
    }
  }'
```

## Run it after collecting credentials

### With the Auth Component

Pass the task's ID as `taskId`. The component runs the task as soon as the credential is stored, shows any interactions in the same UI, and returns the result in `onSuccess` or `onError`. See [Task linking](/components/auth#task-linking).

```tsx theme={null}
<DeckAuthComponent
  token={token}
  sourceId="src_a1b2c3d4..."
  taskId="task_verify..."
  onSuccess={({ credentialId, verified, sessionId }) => {
    if (verified) {
      // The credential works. Run your other tasks.
    }
  }}
  onError={({ code }) => {
    // auth_invalid: ask the user to re-enter their credentials.
  }}
/>
```

### With your own auth flow

After you [store the credential](/guides/building-auth-ui), run the task with it:

```bash Request theme={null}
curl -X POST https://api.deck.co/v2/tasks/task_verify.../run \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "credential_id": "cred_a1b2c3d4...",
    "input": {}
  }'
```

If the source asks for an MFA code or a security question, the run pauses with `interaction_required`. Submit the user's answer to resume the run. See [Interactions](/guides/interactions).

When the run completes, the credential becomes `verified` and Deck sends a `credential.verified` [event](/events/events):

```json Response theme={null}
{
  "id": "trun_a1b2c3d4...",
  "object": "task_run",
  "status": "completed",
  "result": "success",
  "task_id": "task_verify...",
  "credential_id": "cred_a1b2c3d4...",
  "session_id": "sess_x9y8z7...",
  "output": {
    "login_status": true
  },
  "errors": null,
  "interaction": null
}
```

## Continue with task runs

Once the credential is `verified`, run your other tasks with its `credential_id`.

To skip a second sign-in, pass the verification run's `session_id` on the next run. Sessions close after 10 minutes of inactivity. See [Reusing a session](/concepts/sessions#reusing-a-session).

```bash Request theme={null}
curl -X POST https://api.deck.co/v2/tasks/task_x9y8z7.../run \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "credential_id": "cred_a1b2c3d4...",
    "session_id": "sess_x9y8z7...",
    "input": {}
  }'
```

Runs in a new session sign in again. To reduce repeat MFA prompts, enable [credential persistence](/concepts/credentials#credential-persistence).

## Handle failures

If the source rejects the credentials, the run fails with `auth_invalid`, the credential becomes `invalid`, and Deck sends a `credential.invalid` event. Ask the user to [update the credential](/guides/building-auth-ui#updating-credentials) and run the task again.

Other failures, like the source being unavailable, don't change the credential's status. Run the task again later. See [Errors](/api/errors).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.