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

# Securely connecting to APIs

> Connect a Skill to an external API without placing credentials in its instructions or files by configuring protected request headers.

Connect a Skill to an external API without writing an API key or other credential in the Skill's instructions, code, or files.

Cassidy keeps the credential separate from the Skill and adds it at the network layer only when Skill code sends a request to the host you configure.

## Why API keys work this way

Putting an API key in instructions, code, or a file would allow an Agent or anyone who can open the Skill to read and copy it. API Keys & Headers avoids exposing the credential:

1. The Agent and Skill code receive the API host and header name, but not the secret value.
2. The code sends a request without containing the credential.
3. Cassidy adds the secret header at the network layer as the request goes to the matching host.

The API receives the credential and can authenticate the request, but the Agent, generated code, Skill editors, and people using the Skill never receive the stored value.

## When to use this

Use API Keys & Headers when you want to give Agents programmatic access to a service that does not have a Cassidy Connector or an official MCP server.

For example, you could create a Skill that:

* Looks up customer, order, inventory, or account information from an internal API
* Runs approved reports against an internal analytics service
* Checks the status of private systems or operational processes
* Creates tickets or starts approved internal processes
* Works with a legacy or specialized business system that does not offer a ready-made integration

The Skill provides the instructions and code for using the API. API Keys & Headers provides the credential securely. Together, they provide an experience similar to a purpose-built Connector or MCP server without exposing the API key.

<Warning>
  A credential configured on a Skill is shared by everyone who can use that
  Skill. Use a narrowly scoped service account or API key. If each person should
  use their own account and permissions, use a
  [Connector](/agents/connectors/overview) or [MCP
  server](/agents/connectors/mcp-servers) instead.
</Warning>

## Before you start

You need:

* Edit access to the Skill
* An API key, token, or other credential from the service you want to connect
* The API's hostname and required authentication header
* Instructions or code in the Skill that knows how to call the API

The API key feature supplies authentication. It does not teach the Skill which endpoints to call or how to interpret the response.

## Connect the Skill

<Steps>
  <Step title="Check the API's authentication instructions">
    Find the hostname, header name, and value format in the API provider's documentation.

    For example, an API may require:

    * Host: `api.example.com`
    * Header: `Authorization`
    * Value: `Bearer YOUR_API_KEY`

    Other APIs may use a header such as `X-API-Key` and expect only the key as its value.
  </Step>

  <Step title="Open API Keys & Headers">
    Open the Skill editor, select **More options → Advanced → API Keys & Headers**, then click **Add Host**.

    <Frame>
      <img src="https://mintcdn.com/cassidy/cxzNpEw5gi1nbDPw/images/skills/skill-api-keys-menu.png?fit=max&auto=format&n=cxzNpEw5gi1nbDPw&q=85&s=95f8360a6007dcf1655f99a0c2808045" alt="Skill More options menu with API Keys and Headers shown under Advanced" width="824" height="510" data-path="images/skills/skill-api-keys-menu.png" />
    </Frame>
  </Step>

  <Step title="Enter the API host">
    Enter only the hostname, such as `api.example.com`.

    Do not include `https://`, a path such as `/v1`, or a port number.

    <Tip>Use the most specific hostname possible. Wildcards such as `*.example.com` are supported, but they send the configured headers to a broader set of hosts.</Tip>
  </Step>

  <Step title="Add the authentication header">
    Enter the header name required by the API. For credentials, select **Secret** and enter the complete value expected by the provider.

    For a bearer token, include the `Bearer ` prefix:

    ```text theme={null}
    Bearer YOUR_API_KEY
    ```

    Use **Public parameter** only for non-sensitive values that Skill editors can safely read, such as an API version or environment name.
  </Step>

  <Step title="Save and test the Skill">
    Click **Save**, then use the Skill in a test chat and confirm that the API request succeeds.

    Test both a successful request and a request the credential should not be allowed to perform.
  </Step>
</Steps>

## How Cassidy protects secret values

* Secret values are hidden after you save them. Editors can see that a value exists, but cannot retrieve it.
* Cassidy adds the configured headers only to requests matching the host rule.
* Secret values are not included when a Skill is exported.
* People with edit access can replace or remove a secret, but they cannot reveal the saved value.
* API Keys & Headers are Skill-level settings. Changes take effect after saving and do not require publishing a new Skill version.

<Warning>
  **Public parameters are visible to Skill editors.** Never use **Public
  parameter** for API keys, bearer tokens, passwords, or other credentials.
</Warning>

## Security recommendations

* Create a dedicated credential for the Skill instead of using a personal API key.
* Grant only the permissions and data access the Skill needs.
* Prefer read-only access unless the Skill must create or update data.
* Restrict the credential to the provider's exact host when the provider supports it.
* Set an expiration date and rotate the credential regularly.
* Review the API provider's activity logs for unexpected requests.
* Remove the host rule immediately if the credential is compromised.

## Rotate or remove a credential

To rotate a credential, return to **More options → Advanced → API Keys & Headers**, enter the replacement secret, and save.

Leaving an existing secret field blank keeps the current value when its host and header name have not changed. Changing either one requires you to enter the secret again. To stop using the credential, remove its header or host rule and save.

## Troubleshoot failed requests

<AccordionGroup>
  <Accordion title="The API returns 401 Unauthorized">
    Confirm that the header name and value format match the API provider's
    documentation. For an `Authorization` header, check whether the provider
    requires a prefix such as `Bearer `.
  </Accordion>

  <Accordion title="The API returns 403 Forbidden">
    The credential was recognized but may not have permission for that endpoint
    or data. Review the credential's scopes and account access with the API
    provider.
  </Accordion>

  <Accordion title="The authentication header is not being added">
    Confirm that the request hostname exactly matches the configured host. Do
    not put a protocol, path, or port in the host field.
  </Accordion>

  <Accordion title="Different users need different API access">
    A Skill API key is shared. Use a [Connector](/agents/connectors/overview) or
    [MCP server](/agents/connectors/mcp-servers) when each person should
    authenticate with their own account.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Build and edit a Skill" icon="wrench" href="/skills/build-and-configure">
    Add instructions and code that use the connected API.
  </Card>

  <Card title="Share and distribute Skills" icon="users-gear" href="/skills/sharing-and-management">
    Control who can use a Skill connected to a shared credential.
  </Card>
</CardGroup>