> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinyfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Your Vault

> Connect your password manager so TinyFish can securely log into websites during automations

TinyFish can log into websites on your behalf using credentials from your existing password manager. Connect your vault once, then select which credentials to use for each run.

## How It Works

Connect your password manager account, TinyFish syncs your vault items, and then you select specific credentials for each run. Each run only gets the credentials you explicitly choose, so no run has access to your full vault.

<img src="https://mintcdn.com/tinyfish/syPJyeND12dEB_sp/images/vault/empty-vault-state.png?fit=max&auto=format&n=syPJyeND12dEB_sp&q=85&s=d37cb1a9c5f400e4fae5dfafdc3794e0" alt="Vault settings page with Connect a password manager button" width="427" height="317" data-path="images/vault/empty-vault-state.png" />

## Connect Your Provider

<Note>More providers coming soon.</Note>

<Tabs>
  <Tab title="Dashboard">
    In TinyFish, go to **Settings > Vault** and click **Connect a password manager**.

    <img src="https://mintcdn.com/tinyfish/syPJyeND12dEB_sp/images/vault/provider-selector.png?fit=max&auto=format&n=syPJyeND12dEB_sp&q=85&s=0b19db35fe20eb66ef7c2cd1da14d1a5" alt="Provider selection dialog showing 1Password and Bitwarden options" width="516" height="266" data-path="images/vault/provider-selector.png" />

    <AccordionGroup>
      <Accordion title="1Password" icon="key" defaultOpen>
        Paste your Service Account Token (starts with `ops_`), then click **Connect**.

        <img src="https://mintcdn.com/tinyfish/syPJyeND12dEB_sp/images/vault/1password-form.png?fit=max&auto=format&n=syPJyeND12dEB_sp&q=85&s=9481bb6f229ee45f8a840359d535f22c" alt="1Password credentials form with Service Account Token field" width="523" height="333" data-path="images/vault/1password-form.png" />

        Your items sync automatically. Confirm they appear grouped by vault name.

        <img src="https://mintcdn.com/tinyfish/syPJyeND12dEB_sp/images/vault/1password-connected.png?fit=max&auto=format&n=syPJyeND12dEB_sp&q=85&s=f9fa02dda221c7e34591433bca61406b" alt="Vault settings with connected 1Password showing credentials grouped by vault" width="772" height="443" data-path="images/vault/1password-connected.png" />

        <Tip>
          Need a token? Create a service account with read access to your vault. See the [1Password service account docs](https://developer.1password.com/docs/service-accounts/).
        </Tip>
      </Accordion>

      <Accordion title="Bitwarden" icon="shield-halved">
        Enter your `Client ID`, `Client Secret`, and `Master Password`, then click **Connect**.

        Use the format `user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` for the Client ID.

        <img src="https://mintcdn.com/tinyfish/syPJyeND12dEB_sp/images/vault/bitwarden-form.png?fit=max&auto=format&n=syPJyeND12dEB_sp&q=85&s=19c6d01ae5e1ec1ca2dbb9be1026d2c3" alt="Bitwarden credentials form with Client ID, Client Secret, and Master Password fields" width="524" height="562" data-path="images/vault/bitwarden-form.png" />

        If you use a self-hosted instance, toggle **Self-hosted server** and enter your server URL.

        <img src="https://mintcdn.com/tinyfish/syPJyeND12dEB_sp/images/vault/bitwarden-connected.png?fit=max&auto=format&n=syPJyeND12dEB_sp&q=85&s=d7f3cfc462e3c25d61c10ed5a3d63c29" alt="Vault settings with connected Bitwarden showing synced credentials" width="787" height="280" data-path="images/vault/bitwarden-connected.png" />

        <Tip>
          Find your API key in Bitwarden under `Settings` > `Security` > `Keys` > `View API Key`. See the [Bitwarden personal API key guide](https://bitwarden.com/help/personal-api-key/).
        </Tip>

        <Note>
          The first sync may take up to 15 seconds. Subsequent syncs are faster.
        </Note>
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="API">
    Connect a provider programmatically with `POST /v1/vault/connections`. Credentials are validated immediately — if they're invalid, the request fails with a `400`.

    <CodeGroup>
      ```bash 1Password theme={null}
      curl -X POST https://agent.tinyfish.ai/v1/vault/connections \
        -H "X-API-Key: $TINYFISH_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "provider": "1password",
          "token": "ops_your_service_account_token"
        }'
      ```

      ```bash Bitwarden theme={null}
      curl -X POST https://agent.tinyfish.ai/v1/vault/connections \
        -H "X-API-Key: $TINYFISH_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "provider": "bitwarden",
          "clientId": "user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "clientSecret": "your_client_secret",
          "masterPassword": "your_master_password"
        }'
      ```

      ```bash Bitwarden (self-hosted) theme={null}
      curl -X POST https://agent.tinyfish.ai/v1/vault/connections \
        -H "X-API-Key: $TINYFISH_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "provider": "bitwarden",
          "clientId": "user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "clientSecret": "your_client_secret",
          "masterPassword": "your_master_password",
          "serverUrl": "https://bitwarden.example.com"
        }'
      ```
    </CodeGroup>

    A successful response includes the `connectionId` and the initial list of synced items:

    ```json theme={null}
    {
      "connectionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "connected": true,
      "provider": "1password",
      "items": [
        {
          "item_id": "cred:a1b2c3d4-5678-90ab-cdef-1234567890ab:Personal:item-xyz",
          "label": "Amazon Login",
          "vault_name": "Personal",
          "websites": ["https://amazon.com"],
          "has_totp": false,
          "connectionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
        }
      ]
    }
    ```

    If the connection already exists for the same provider, it is replaced — not duplicated.
  </Tab>

  <Tab title="CLI">
    Connect a provider with `tinyfish vault connection add`. Provider secrets are read from environment variables — never passed as flags — so they stay out of shell history.

    <CodeGroup>
      ```bash 1Password theme={null}
      TINYFISH_VAULT_TOKEN=ops_your_service_account_token \
        tinyfish vault connection add --provider 1password
      ```

      ```bash Bitwarden theme={null}
      TINYFISH_VAULT_CLIENT_SECRET=your_client_secret \
      TINYFISH_VAULT_MASTER_PASSWORD=your_master_password \
        tinyfish vault connection add \
          --provider bitwarden \
          --client-id user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      ```

      ```bash Bitwarden (self-hosted) theme={null}
      TINYFISH_VAULT_CLIENT_SECRET=your_client_secret \
      TINYFISH_VAULT_MASTER_PASSWORD=your_master_password \
        tinyfish vault connection add \
          --provider bitwarden \
          --client-id user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
          --server-url https://bitwarden.example.com
      ```
    </CodeGroup>

    If the connection already exists for the same provider, it is replaced — not duplicated.

    <Tip>
      Need a 1Password token? Create a service account with read access to your vault. See the [1Password service account docs](https://developer.1password.com/docs/service-accounts/).
    </Tip>
  </Tab>
</Tabs>

## Managing Your Vault

<Tabs>
  <Tab title="Dashboard">
    ### Sync

    Click `Sync` to fetch the latest items from your connected provider.

    ### Disconnect

    Click `Disconnect` and confirm to remove the provider. All cached credentials are removed immediately, but runs already in progress are not affected. You can reconnect at any time.
  </Tab>

  <Tab title="API">
    ### List connections

    ```bash theme={null}
    curl https://agent.tinyfish.ai/v1/vault/connections \
      -H "X-API-Key: $TINYFISH_API_KEY"
    ```

    ```json theme={null}
    {
      "connections": [
        {
          "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
          "provider": "1password",
          "connectionStatus": "active",
          "lastValidatedAt": "2026-04-10 12:00:00"
        }
      ]
    }
    ```

    ### List vault items

    Retrieve the credential items available for runs. These are read from the local cache, so the response is fast.

    ```bash theme={null}
    curl https://agent.tinyfish.ai/v1/vault/items \
      -H "X-API-Key: $TINYFISH_API_KEY"
    ```

    ```json theme={null}
    {
      "items": [
        {
          "itemId": "cred:a1b2c3d4-5678-90ab-cdef-1234567890ab:Personal:item-xyz",
          "connectionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
          "label": "Amazon Login",
          "vaultName": "Personal",
          "domains": ["amazon.com"],
          "fieldMetadata": [
            { "fieldId": "username", "label": "username", "type": "STRING" },
            { "fieldId": "password", "label": "password", "type": "STRING" }
          ],
          "hasTotp": false
        }
      ]
    }
    ```

    The `itemId` is the value you pass as `credential_item_ids` when [starting a run](/key-concepts/credentials#using-the-api).

    <Note>
      Items without website URLs in your password manager will still sync, but they won't have any `domains` and can't be matched to a site during a run.
    </Note>

    ### Sync items

    Pull the latest state from your connected providers. Use this before starting a run if you've recently changed passwords.

    ```bash theme={null}
    curl -X POST https://agent.tinyfish.ai/v1/vault/items/sync \
      -H "X-API-Key: $TINYFISH_API_KEY"
    ```

    ```json theme={null}
    {
      "items": [ ... ],
      "sync_summary": {
        "added": 3,
        "updated": 1,
        "removed": 0
      }
    }
    ```

    ### Disconnect a provider

    Removes the connection and all cached credentials. Runs already in progress are not affected.

    ```bash theme={null}
    curl -X DELETE https://agent.tinyfish.ai/v1/vault/connections/a1b2c3d4-5678-90ab-cdef-1234567890ab \
      -H "X-API-Key: $TINYFISH_API_KEY"
    ```

    ```json theme={null}
    {
      "disconnected": true,
      "connectionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
    }
    ```
  </Tab>

  <Tab title="CLI">
    ### List connections

    ```bash theme={null}
    tinyfish vault connection list
    ```

    ### Sync items

    Pull the latest credentials from your connected providers. Run this after adding new credentials or changing passwords.

    ```bash theme={null}
    tinyfish vault item sync
    ```

    ### List items

    List all synced credential items. The `itemId` is what you pass to `--credential-item-id` when running an automation.

    ```bash theme={null}
    tinyfish vault item list
    ```

    ### Disconnect a provider

    Removes the connection and all cached credentials. Runs already in progress are not affected.

    ```bash theme={null}
    tinyfish vault connection remove a1b2c3d4-5678-90ab-cdef-1234567890ab
    ```
  </Tab>
</Tabs>

## Using the Vault API

### Quick start

Connect a provider, retrieve item IDs, and start a run with specific credentials:

```bash theme={null}
# 1. Connect your vault (one-time setup)
curl -X POST https://agent.tinyfish.ai/v1/vault/connections \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "1password", "token": "ops_your_token" }'
# → returns connectionId and initial items

# 2. List available credentials (reads from cache — fast)
curl -s https://agent.tinyfish.ai/v1/vault/items \
  -H "X-API-Key: $TINYFISH_API_KEY"
# → grab the itemId for the credential you need

# 3. Start a run with that credential
curl -X POST https://agent.tinyfish.ai/v1/automation/run \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.linkedin.com",
    "goal": "Log in and capture the latest 3 posts from the feed",
    "use_vault": true,
    "credential_item_ids": [
      "cred:a1b2c3d4-5678-90ab-cdef-1234567890ab:Work:item-linkedin"
    ]
  }'
```

### Matching credentials to URLs

Filter items by the `domains` field to find the right credential for your target site:

```bash theme={null}
curl -s https://agent.tinyfish.ai/v1/vault/items \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  | jq '.items[] | select(.domains[] | contains("linkedin.com")) | .itemId'
```

Scoping to specific `credential_item_ids` is more reliable than `use_vault: true` alone — it prevents the agent from picking the wrong login when you have multiple accounts on the same domain.

### When to sync

`GET /v1/vault/items` reads from a local cache and is fast. You don't need to sync before every run.

Call `POST /v1/vault/items/sync` when:

* You've recently changed a password in your vault
* You've added new credentials you want to use
* A run failed to log in and you suspect stale credentials

For most pipelines, syncing once at startup or on a daily schedule is sufficient.

### Handling expired connections

Provider tokens can expire. When they do, `POST /v1/vault/items/sync` returns a `401`. Your pipeline should:

1. Catch the `401` from sync
2. Re-connect with `POST /v1/vault/connections` using a fresh token
3. Retry the sync

1Password service account tokens don't expire unless revoked. Bitwarden tokens may expire based on your server configuration.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection failed — invalid credentials" icon="xmark">
    For 1Password, verify the token starts with `ops_` and has read access to the vault you want to sync.

    For Bitwarden, verify that the `Client ID` and `Client Secret` match the same API key.

    The API returns a `400` with `"Invalid vault token"` when credentials fail validation.
  </Accordion>

  <Accordion title="Vault items not appearing after sync" icon="circle-question">
    Vault items must have website URLs in your password manager to sync into TinyFish.

    Credentials without URLs are not synced.
  </Accordion>

  <Accordion title="Self-hosted Bitwarden not connecting" icon="server">
    Ensure the server URL includes `https://` and that the server is accessible from TinyFish.
  </Accordion>

  <Accordion title="Token expired or reconnect required" icon="rotate">
    Provider tokens can expire. Disconnect the provider, then reconnect using a fresh token or updated credentials.

    `POST /v1/vault/items/sync` returns a `401` when all connections require reconnect and no items can be returned.
  </Accordion>

  <Accordion title="First sync is slow" icon="clock">
    The first Bitwarden sync can take up to 15 seconds while the connection initializes. Subsequent syncs are faster.
  </Accordion>

  <Accordion title="All providers already connected" icon="link">
    You can connect a maximum of 2 providers at the same time.
  </Accordion>

  <Accordion title="API returns 404 on vault items" icon="circle-exclamation">
    No vault connections exist yet. Connect a provider first with `POST /v1/vault/connections`.
  </Accordion>

  <Accordion title="API returns 503" icon="server">
    The vault integration is unavailable or the backing vault service returned an error.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Vault Credentials" icon="key" href="/key-concepts/credentials">
    Learn how credentials are selected and used in runs
  </Card>

  <Card title="Authentication" icon="lock" href="/authentication">
    Understand TinyFish authentication methods
  </Card>
</CardGroup>