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

# Secrets

> Store reusable account secrets and track where they are used

export const Screenshot = ({lightSrc, darkSrc, alt, caption, maxWidth = "880px"}) => {
  return <div style={{
    margin: "1rem auto",
    maxWidth,
    width: "100%"
  }}>
      <Frame>
        <img className="block dark:hidden" src={lightSrc} alt={alt} />
        <img className="hidden dark:block" src={darkSrc} alt={alt} />
      </Frame>
      {caption ? <p style={{
    marginTop: "0.5rem",
    fontSize: "0.875rem",
    color: "inherit",
    opacity: 0.8
  }}>
          {caption}
        </p> : null}
    </div>;
};

Secrets let you centralize reusable credentials for the current account instead of repeating raw values across supported configurations.

**Access:** Go to **Settings → Developers → Secrets**.

<Screenshot light="/images/accounts__secrets-light.png" dark="/images/accounts__secrets-dark.png" alt="Secrets inventory page with saved secrets and usage information" />

## Where Secrets Are Used

The current product uses saved secrets in multiple places, including:

* Cal.com integration credentials
* SIP trunk authentication passwords
* MCP server headers and query parameters
* custom API actions and other agent-side authenticated calls

That makes the Secrets page the safest place to rotate shared credentials without hunting through each feature manually.

## Create a Secret

<Steps>
  <Step title="Open Secrets">
    Navigate to **Settings → Developers → Secrets**.
  </Step>

  <Step title="Create a new secret">
    Click **New Secret**.
  </Step>

  <Step title="Set the name and value">
    Enter a clear name and paste the secret value.
  </Step>

  <Step title="Choose whether it starts enabled">
    Leave **Enabled** on for active use, or turn it off if you want to save the value before rollout.
  </Step>

  <Step title="Save">
    Submit the form to add the secret to the inventory.
  </Step>
</Steps>

<Tip>
  Use names that identify provider, purpose, and environment, such as `calcom-prod-api-key` or `crm-staging-webhook-token`.
</Tip>

## Inventory and Statuses

The inventory table shows:

* **Name**
* **Status**
* **Usage count**
* **Last used**

Current statuses:

| Status       | Meaning                                                             |
| ------------ | ------------------------------------------------------------------- |
| **Active**   | The secret is enabled and ready for supported references            |
| **Disabled** | The secret stays stored but should not be used for active workflows |
| **Missing**  | A referenced secret value is unavailable and needs attention        |

If a secret has no active references, the expanded row shows **No active references yet**.

## Edit, Disable, and Rotate

* Edit a secret to rename it or replace the stored value.
* When you edit an existing secret, you can leave the value blank to keep the current value.
* Disable a secret when you want to pause new usage without deleting the record.
* Review usage references before rotation so you know which downstream flows are affected.

## Delete Behavior

You can delete a secret only when it is not in use.

If a secret still has active references, the platform blocks deletion until you remove or update those references.

## Best Practices

<AccordionGroup>
  <Accordion title="Create one secret per integration context" icon="key">
    Keep production, staging, and sandbox credentials separate so you can rotate or disable them independently.
  </Accordion>

  <Accordion title="Name secrets for searchability" icon="tag">
    Prefer stable, descriptive names over generic labels like `API key` or `token`.
  </Accordion>

  <Accordion title="Rotate after exposure or ownership changes" icon="rotate">
    Replace values immediately after a suspected leak or when the owning system changes.
  </Accordion>

  <Accordion title="Review unused secrets regularly" icon="clipboard-list">
    Remove stale credentials once you confirm they are no longer referenced.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Integrations" icon="plug" href="/accounts/integrations">
    Connect third-party services for supported workflows
  </Card>

  <Card title="Webhooks" icon="webhook" href="/accounts/webhooks">
    Configure signed event delivery to your own systems
  </Card>

  <Card title="API Keys" icon="key" href="/accounts/api-keys">
    Manage direct programmatic access to the platform
  </Card>

  <Card title="Custom API Actions" icon="code" href="/build/tools/custom-api-actions">
    Use external APIs from your agents
  </Card>
</CardGroup>