Custom App Connections

When would I use a custom app connection?

Not every service supports OAuth. Some APIs authenticate with API keys, bearer tokens, or other credentials. Custom app connections let you link these services to your Claw by storing the credentials securely in your team's vault. Common examples include internal APIs, niche SaaS tools, and services where you need a personal API key rather than an OAuth grant.

How do I create a custom app connection?

1. Navigate to Settings > Connections and select the Claw you want to configure.
2. Click Add Connection and choose Custom App.
3. Fill in the connection details:
   • Name — A descriptive label for this connection (e.g., "Acme CRM API" or "Weather Service").
   • Base URL — The root URL of the API the Claw will call.
   • Auth type — Choose between API Key, Bearer Token, or Custom Header.
   • Credential — Enter the key or token. This value is encrypted and stored as a vault item.
4. Optionally add a label to the vault item for easier identification. Labels are visible in the vault manager but the credential value is always masked after saving.
5. Click Save. WorkClaw tests the connection by making a lightweight health-check request to the base URL.

How are credentials stored?

All custom app credentials are stored as encrypted vault items. WorkClaw never displays the full credential after initial entry — only a masked preview and the label you assigned. Vault items are scoped to your team and accessible only to Claws with the connection assigned.

You can manage vault items directly from Settings > Vault. Each item shows its label, which connections reference it, and when it was last rotated. See Vault and Security for details on access control and rotation policies.

How do skills reference custom connections?

Skills that need custom API access declare a provider: custom entry in their REQUIREMENTS.yaml with an identifier and expected auth type. When you install such a skill, WorkClaw matches the requirement against your existing custom connections or prompts you to create one.

connections:
  - provider: custom
    identifier: acme-crm
    authType: api_key
    required: true

Can I use the same custom connection across multiple Claws?

Yes. When you add a connection to a second Claw, you can reference an existing vault item rather than entering the credential again. The vault item is shared, but each Claw's connection configuration (base URL, headers) is independent.

How do I rotate a credential?

Go to Settings > Vault, find the vault item, and click Rotate. Enter the new credential value. All connections referencing that vault item pick up the new value immediately — no need to update each connection individually. See Managing Connections for post-rotation health checks.