---
title: API Keys
description: Create scoped API keys to access management tools, proxies, and agents
icon: KeyRound
---

import Callout from "../../../../components/ui/Callout.astro";

## What are API Keys?

API keys let external systems connect to deco Studio without needing a user to log in. They're simple tokens you can use in scripts, automation tools, or any system that needs to access deco Studio programmatically.

<Callout type="warning">
  API keys are for **external systems connecting to deco Studio**. To connect deco Studio to upstream MCP servers, see [Connections](/en/studio/connections).
</Callout>

## When to Use API Keys vs OAuth

**OAuth** (Recommended for most users)
- Use with Cursor, Claude Desktop, VS Code
- Login with your browser
- Easiest setup

**API Keys**
- Use for scripts and automation
- No browser login needed
- Better for servers and CI/CD

## Creating an API Key

API keys are managed through the management MCP tools or the API. When creating an API key, you specify:

1. A descriptive name (like "My Automation Script")
2. Direct permissions in the format `{ resource: [actions...] }` — where the resource is either `"self"` for management tools or `"conn_<UUID>"` for connection-specific access
3. **Copy the key immediately** — it is only shown once

<Callout type="error">
  You can only see the API key once. Store it somewhere safe like a password manager.
</Callout>

## Using Your API Key

Add the API key to your MCP client configuration:

```json
{
  "mcpServers": {
    "deco": {
      "url": "https://studio.decocms.com/api/your-org-slug/mcp/gateway/your-agent-id",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer mcp_key_abc123..."
      }
    }
  }
}
```

Replace `your-org-slug` with your organization's slug and `your-agent-id` with the agent's id. See the [Connection Proxy](/en/studio/api-reference/connection-proxy) reference for the full path scheme.

## Security Best Practices

<Callout type="warning">
  Treat API keys like passwords. Never share them or commit them to code repositories.
</Callout>

**Give minimum permissions**: Only grant what's actually needed.

**Create separate keys**: Use one key per tool or script—easier to manage if something goes wrong.

**Store securely**: Keep keys in a password manager or secrets manager, never in plain text files.

**Rotate regularly**: Create new keys every few months and delete old ones.

**Monitor usage**: Check the dashboard regularly for unusual activity.

<Callout type="tip">
  Combine API keys with [Agents](/en/studio/agents) to control exactly which tools your scripts can access.
</Callout>

