Verify credentials

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 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 covers those steps. To collect credentials, use the Auth Component or build your own auth flow.

Create the task

The task takes no input and returns login_status. It returns metadata only, so leave storage off. See Tasks for guidance on writing prompts. Use this prompt:

Prompt

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:

Request

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.

<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, run the task with it:

Request

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. When the run completes, the credential becomes verified and Deck sends a credential.verified event:

Response

{
  "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.

Request

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.

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

Get Started

Guides

Development

Platform

Integrations

Migration Guides

Verify credentials

Prerequisites

Create the task

Run it after collecting credentials

With the Auth Component

With your own auth flow

Continue with task runs

Handle failures

​Prerequisites

​Create the task

​Run it after collecting credentials

​With the Auth Component

​With your own auth flow

​Continue with task runs

​Handle failures

Prerequisites

Create the task

Run it after collecting credentials

With the Auth Component

With your own auth flow

Continue with task runs

Handle failures