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

# Chaves de API e autenticação

> Crie uma chave de API e envie-a no cabeçalho X-API-Key pela API REST, CLI ou servidor MCP. Clientes MCP também podem se conectar com OAuth (PKCE).

## Autenticação por chave de API

As requisições da API REST usam uma chave de API enviada no cabeçalho `X-API-Key`. Clientes MCP podem usar uma chave de API ou OAuth com PKCE aprovado pelo usuário.

Agentes de IA podem começar pelo [Auth.md](https://so-me.studio/auth.md) para descoberta de OAuth, registro de cliente, consentimento do usuário, renovação de token e provisionamento de chave de API para a CLI.

```bash theme={null}
X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

## Gerar uma chave de API

**1. Entre no seu painel**

Acesse o [Social media studio](https://so-me.studio/pt-BR) e entre na sua conta.

**2. Abra as configurações de API**

Navegue até **Configurações** > aba **API**.

**3. Crie uma nova chave**

Clique em **Nova chave de API** e dê um nome a ela.

**4. Escolha o acesso**

Mantenha **Acesso total**, ou selecione **Restrito** e defina cada recurso como **Sem acesso**, **Leitura** ou **Leitura e escrita**. Veja [Scopes](#scopes).

**5. Copie a chave**

Clique em **Criar** e copie a chave.

> [!WARNING]
>
> A chave completa é exibida apenas uma vez. Guarde-a com segurança. Se você a perder, revogue a chave e crie uma nova.

## Permissões

Somente os **proprietários** do espaço de trabalho podem criar, listar e revogar chaves de API. Uma chave age em nome do espaço de trabalho em que foi criada, restrita aos dados desse espaço. Se um proprietário sair ou tiver o acesso alterado, revogue e reemita as chaves que ele criou.

## Scopes

Uma chave tem **acesso total**, a menos que você defina scopes ao criá-la. Toda chave criada antes de os scopes existirem mantém o acesso total.

Uma chave com scopes só pode chamar os endpoints cobertos por eles. Qualquer outro endpoint retorna `403 Forbidden` com o scope ausente na mensagem.

* Um endpoint `GET` exige `<resource>:read`.
* Um endpoint `POST`, `PUT`, `PATCH` ou `DELETE` exige `<resource>:write`.
* `<resource>:write` inclui `<resource>:read`.

| Recurso | Scopes | Endpoints |
| - | - | - |
| `accounts` | `accounts:read`, `accounts:write` | `/v1/accounts` |
| `posts` | `posts:read`, `posts:write` | `/v1/posts`, `/v1/drafts`, `/v1/approvals` |
| `media` | `media:read`, `media:write` | `/v1/media` |
| `analytics` | `analytics:read` | `/v1/analytics` |
| `inbox` | `inbox:read`, `inbox:write` | `/v1/inbox` |
| `ai` | `ai:read`, `ai:write` | `/v1/ai` |
| `biolinks` | `biolinks:read`, `biolinks:write` | `/v1/biolinks` |
| `teams` | `teams:read`, `teams:write` | `/v1/teams` |
| `settings` | `settings:read`, `settings:write` | `/v1/settings` (veja as exceções abaixo) |
| `webhooks` | `webhooks:read`, `webhooks:write` | `/v1/webhooks` |
| `support` | `support:read`, `support:write` | `/v1/support` |
| `templates` | `templates:read` | `/v1/templates` |
| `whatsapp` | `whatsapp:read`, `whatsapp:write` | `/v1/whatsapp` |

Exceções:

* `POST /v1/media/validate` exige apenas `media:read`, porque não altera nada.
* `POST /v1/templates/{id}/render` exige apenas `templates:read`.
* Estes endpoints exigem uma chave de acesso total: `PATCH /v1/settings/profile`, todo o `/v1/settings/api-keys` e todo o `/v1/settings/tenants`. Uma chave com scopes não pode criar uma nova chave nem acessar outros espaços de trabalho.
* O servidor MCP não aceita chaves com scopes. Use uma chave de acesso total ou conecte com OAuth.
* `teams:write` não pode convidar nem promover proprietários. Somente uma chave de acesso total pode conceder a função `owner`.
* Uma chave com scopes só pode assinar, listar e reenviar os eventos de webhook que pode ler. Por exemplo, os eventos de `inbox` exigem `inbox:read`, e os eventos de `post`, `draft` e `approval` exigem `posts:read`. Os eventos `knowledge`, `organization`, `account`, `auth`, `api_key`, `integration`, `subscription`, `referral`, `mcp` e `quota` exigem uma chave de acesso total.

Para criar uma chave com scopes pela API, envie `scopes` para `POST /v1/settings/api-keys` com uma chave de acesso total:

```bash theme={null}
curl https://api.so-me.studio/v1/settings/api-keys \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Zapier", "scopes": ["accounts:read", "posts:write", "media:write"]}'
```

Omita `scopes` para uma chave de acesso total. Não é possível alterar os scopes de uma chave. Revogue-a e crie uma nova.

## Usar sua chave de API

### API REST

Envie a chave no cabeçalho `X-API-Key`:

```bash theme={null}
curl https://api.so-me.studio/v1/posts \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
```

### Servidor MCP

O servidor MCP usa a mesma chave de API. Ele aceita apenas chaves de acesso total. Envie a chave no cabeçalho `X-API-Key` da sua configuração MCP:

```json theme={null}
{
  "mcpServers": {
    "so-me-studio": {
      "url": "https://api.so-me.studio/mcp",
      "headers": {
        "X-API-Key": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

## Requisitos de plano

O acesso à API REST, à CLI e ao MCP está disponível nos planos **Standard**, **Advanced** e **Lifetime**. O plano **Lite** não inclui acesso à API, à CLI nem ao MCP.

| Plano | Acesso à API |
| - | - |
| Lite | Não |
| Standard | Sim |
| Advanced | Sim |
| Lifetime | Sim |

Para detalhes completos dos planos, veja a [visão geral de faturamento](/pt-BR/billing/overview.md).

## Limite de requisições

As requisições da API têm limite de taxa por espaço de trabalho, e o limite exato depende do seu plano. Ao exceder o limite, você receberá uma resposta `429 Too Many Requests`: aguarde a janela reiniciar e tente de novo.

As chamadas de ferramentas MCP também consomem créditos conforme o seu plano. Confira seu uso em **Configurações** > **API** e veja [Créditos de IA](/pt-BR/get-started/ai-credits.md) para entender como os créditos funcionam.

> [!NOTE]
>
> Planos mais altos têm limites de taxa maiores e franquias mensais de uso da API maiores. Veja a [visão geral de faturamento](/pt-BR/billing/overview.md) para os limites do seu plano.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.