Connect Your Vault

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.

Vault credentials are currently supported in the Playground and REST API. Python SDK, TypeScript SDK, and CLI support is coming soon.

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.

Vault settings page with Connect a password manager button

Connect Your Provider

More providers coming soon.

Dashboard
API

In TinyFish, go to Settings > Vault and click Connect a password manager.

1Password

Paste your Service Account Token (starts with ops_), then click Connect.

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

Vault settings with connected 1Password showing credentials grouped by vault

Need a token? Create a service account with read access to your vault. See the 1Password service account docs.

Bitwarden

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.

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

Vault settings with connected Bitwarden showing synced credentials

Find your API key in Bitwarden under Settings > Security > Keys > View API Key. See the Bitwarden personal API key guide.

The first sync may take up to 15 seconds. Subsequent syncs are faster.

Connect a provider programmatically with POST /v1/vault/connections. Credentials are validated immediately — if they’re invalid, the request fails with a 400.

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"
  }'

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

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

Managing Your Vault

Dashboard
API

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.

List connections

curl https://agent.tinyfish.ai/v1/vault/connections \
  -H "X-API-Key: $TINYFISH_API_KEY"

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

curl https://agent.tinyfish.ai/v1/vault/items \
  -H "X-API-Key: $TINYFISH_API_KEY"

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

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.

Sync items

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

curl -X POST https://agent.tinyfish.ai/v1/vault/items/sync \
  -H "X-API-Key: $TINYFISH_API_KEY"

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

curl -X DELETE https://agent.tinyfish.ai/v1/vault/connections/a1b2c3d4-5678-90ab-cdef-1234567890ab \
  -H "X-API-Key: $TINYFISH_API_KEY"

{
  "disconnected": true,
  "connectionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}

Using the Vault API

Quick start

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

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

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:

Catch the 401 from sync
Re-connect with POST /v1/vault/connections using a fresh token
Retry the sync

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

Troubleshooting

Connection failed — invalid credentials

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.

Vault items not appearing after sync

Vault items must have website URLs in your password manager to sync into TinyFish.Credentials without URLs are not synced.

Self-hosted Bitwarden not connecting

Ensure the server URL includes https:// and that the server is accessible from TinyFish.

Token expired or reconnect required

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.

First sync is slow

The first Bitwarden sync can take up to 15 seconds while the connection initializes. Subsequent syncs are faster.

All providers already connected

You can connect a maximum of 2 providers at the same time.

API returns 404 on vault items

No vault connections exist yet. Connect a provider first with POST /v1/vault/connections.

API returns 503

The vault integration is unavailable or the backing vault service returned an error.

Vault Credentials

Learn how credentials are selected and used in runs

Authentication

Understand TinyFish authentication methods

Start Here

Agent API

Search API

Fetch API

Browser API

Capabilities

Tools & Integrations

Guides

Use Cases

Reference

How It Works

Connect Your Provider

Managing Your Vault

Sync

Disconnect

List connections

List vault items

Sync items

Disconnect a provider

Using the Vault API

Quick start

Matching credentials to URLs

When to sync

Handling expired connections

Troubleshooting

Vault Credentials

Authentication

Start Here

Agent API

Search API

Fetch API

Browser API

Capabilities

Tools & Integrations

Guides

Use Cases

Reference

​How It Works

​Connect Your Provider

​Managing Your Vault

​Sync

​Disconnect

​List connections

​List vault items

​Sync items

​Disconnect a provider

​Using the Vault API

​Quick start

​Matching credentials to URLs

​When to sync

​Handling expired connections

​Troubleshooting

​Related

Vault Credentials

Authentication

How It Works

Connect Your Provider

Managing Your Vault

Sync

Disconnect

List connections

List vault items

Sync items

Disconnect a provider

Using the Vault API

Quick start

Matching credentials to URLs

When to sync

Handling expired connections

Troubleshooting

Related