# Credentials

Saved credentials let Slideshot log into the target app while recording without prompting the agent for input mid-run. Credentials are scoped to a domain, encrypted at rest, and never returned in plaintext from the API.

This page covers the credential management endpoints. For how to actually use a credential during a run, see [Login to any web app](/docs/authentication).

## When to save a credential

Save a credential up front whenever:

- The target app requires login before the workflow can be recorded.
- You expect to record against the same app more than once.
- You want the agent to skip the manual sign-in step entirely.

For OTP-only or magic-link flows, save an email-only credential. Slideshot will still drive the email input and pause for the code mid-run.

## Endpoints

- `POST /v1/agent/credentials`: Create a credential.
- `GET /v1/agent/credentials`: List credentials visible to the calling API key.
- `POST /v1/agent/credentials/:id/set-default`: Mark a credential as the domain default.
- `DELETE /v1/agent/credentials/:id`: Hard-delete a credential.

## Create a credential

```bash
curl -X POST https://api.slideshot.ai/v1/agent/credentials \
  -H "x-api-key: $SLIDESHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Example app: demo account",
    "domain": "app.example.com",
    "email": "demo@example.com",
    "password": "...",
    "is_default": true
  }'
```

Fields:

- `label`: Human-readable name. Required.
- `domain`: Hostname Slideshot matches against `target_url` when the run runs. Required.
- `email`: Email used for login. Required.
- `password`: Optional. Omit for OTP or magic-link-only flows.
- `is_default`: Optional. When `true`, this credential becomes the per-domain default so runs with `auth.source="default"` pick it up automatically.

The response includes credential metadata but never the password or any ciphertext.

## List credentials

```bash
curl https://api.slideshot.ai/v1/agent/credentials \
  -H "x-api-key: $SLIDESHOT_API_KEY"
```

```json
{
  "data": [
    {
      "id": "0a1b2c3d-4e5f-6789-abcd-ef0123456789",
      "label": "Example app: demo account",
      "domain": "app.example.com",
      "email": "demo@example.com",
      "has_password": true,
      "is_default": true,
      "created_at": "2026-05-11T12:00:00Z",
      "updated_at": "2026-05-11T12:00:00Z"
    }
  ]
}
```

API key callers only see credentials their key created. The CLI exposes the same list with `slideshot credentials list`.

## Set or change the default

```bash
curl -X POST https://api.slideshot.ai/v1/agent/credentials/$CRED_ID/set-default \
  -H "x-api-key: $SLIDESHOT_API_KEY"
```

Only one credential per domain can be the default. Setting a new default automatically clears the flag on the previous one.

## Delete a credential

```bash
curl -X DELETE https://api.slideshot.ai/v1/agent/credentials/$CRED_ID \
  -H "x-api-key: $SLIDESHOT_API_KEY"
```

Hard delete: there is no recovery. Runs in flight that referenced the deleted credential continue with the credential they already resolved. New runs that name the same `id` will fail at execution.

## Using a credential at run time

Set `options.auth` on `POST /v1/agent/runs`:

- `{ "source": "none" }`: Record without logging in.
- `{ "source": "default" }`: Use the default credential for the target domain. If none is set, the run proceeds without logging in.
- `{ "source": "saved", "id": "<uuid>" }`: Use an explicit credential. The credential must be owned by the caller and the domain must match the `target_url` hostname.

Failure modes:

- `400` at create time when `auth.saved.id` is not a UUID.
- The run fails at execution if a `saved` credential is missing, not owned by the caller, or its domain does not match the target URL.
- `auth.source="default"` with no default credential is non-fatal. The run proceeds without credentials and the agent will stop at the login screen if the workflow needs one.

## Related

- [Runs](/docs/api/runs): pass a saved credential via `options.auth` when creating a run.
- [Login to any web app](/docs/authentication): conceptual guide to target-app authentication.
- [API overview](/docs/api/overview): request shape, errors, and authentication.