API Keys

Hydra's API keys let external tools — Claude Desktop, Claude Code, Cursor, n8n, Zapier, and any other system that speaks HTTP — read and write data in your Hydra tenant. CRM records, conversations, knowledge articles, tickets, flows, platform metadata, and more.

All keys are created and managed from Settings → API Access.

Create a key

1. Go to Settings → API Access.
2. Click New API key.
3. Give it a name — something that tells you later where it's being used (e.g. "Claude Desktop — Devon", "Zapier webhook", "Internal dashboard").
4. Pick scopes. Each scope gates a category of tool:
   • crm:read / crm:write — leads, contacts, accounts, opportunities
   • conversations:read / conversations:write — inbox, messages, assignments
   • knowledge:read / knowledge:write — knowledge-base articles
   • tickets:read / tickets:write — tickets
   • reports:read — analytics
   • flows:read / flows:trigger — automation flows
   • mini-apps:invoke — published mini-apps
   • manifest:read — platform configuration (objects, events, fields, actions) for external integrations
   • admin:* — team, channels, bots, widgets, key management (Admins only)
5. (Optional) Set a monthly call cap to limit how many API calls this specific key can make. Leave blank to share your tenant's overall budget.
6. Click Create key.

You'll see the raw token once. Copy it immediately — Hydra only stores its hash, so we can't show it to you again. If you lose it, revoke the key and create a new one.

Install the Hydra MCP in Claude Desktop / Claude Code

1. Install the package: npm install -g @hydra-help/mcp.
2. Add to your Claude config:

{
  "mcpServers": {
    "hydra": {
      "command": "npx",
      "args": ["@hydra-help/mcp"],
      "env": {
        "HYDRA_API_KEY": "hmcp_your_token_here"
      }
    }
  }
}

Or point Claude directly at the hosted endpoint:

{
  "mcpServers": {
    "hydra": {
      "url": "https://mcp.hydra-help.com/mcp",
      "headers": {
        "Authorization": "Bearer hmcp_your_token_here"
      }
    }
  }
}

Restart Claude. The first time you ask it to do something Hydra-related ("show my leads", "draft a reply to the last message from Jane"), it will call the MCP and return the result.

Roles and scope ceilings

• Admins and Owners can mint keys with any scope, including admin:*.
• Members can mint keys only within the Member scope set: CRM, Conversations, Knowledge (read-only), Tickets, and Reports (read-only). If a Member needs an admin-scoped key, ask an Admin to create it.

This is a security measure: a leaked Member-created key can never be used to invite new admins or revoke other keys, because the key's permissions are capped at what the creator could do themselves.

Revoking keys

Click Revoke next to any active key. Any clients using that key will start getting 401 Unauthorized on the next call. You can't un-revoke a key — create a new one instead.

• Admins can revoke any key in the tenant.
• Members can only revoke keys they themselves created.

Usage and billing

Every MCP call — whether it comes through stdio or the hosted HTTP server — counts toward your tenant's monthly usage meter, shown at the top of this page. Billing is planned to include an MCP-call component; meter data is already being collected so you can see trends before billing turns on.

Write actions require confirmation

Any MCP tool that changes state in Hydra (creating a lead, posting a message, assigning a conversation) returns a preview first. The calling AI must then call a second confirm tool with the preview's nonce to actually execute the write. This prevents prompt-injection attacks where a malicious message in a conversation transcript tries to trick the AI into running destructive tools. Reads require no confirmation.

Security best practices

• Rotate keys periodically. Even without a known leak, a scheduled monthly or quarterly rotation limits the damage from a compromise you didn't notice.
• Scope narrowly. A dashboard that only needs to read conversations should get conversations:read — not crm:write or anything admin.
• Use per-key caps. A runaway integration that accidentally loops can burn through an unlimited key fast. A 10,000-call-per-month cap is a cheap safety net.
• Treat the raw token as a password. Don't commit it to git, don't paste it in Slack, don't leave it in a shared doc.