# Autenticação

> Envie a chave de API em toda requisição e escolha o workspace quando a chave alcançar mais de um.

Toda requisição leva uma chave de API. A chave define a conta, o workspace e de quem saem os créditos.

## Crie uma chave

Abra [Chaves de API](https://cut.pro/studio/me/api-keys) e clique em **Nova chave**. A chave aparece uma vez só: copie e guarde no seu cofre de segredos. Chaves de API estão nos planos Gratuito, Básico, Plus e Pro.

> A chave gasta créditos e publica nas contas conectadas do workspace. Deixe-a no servidor, em variável de ambiente. Nunca no navegador, no app ou no repositório.

## Envie a chave

Use o header `X-Api-Key`:

```bash
curl https://api.cut.pro/api/v1/workspace \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

Ou `Authorization: Bearer`, se o seu cliente HTTP já monta esse header:

```bash
curl https://api.cut.pro/api/v1/workspace \
  -H "Authorization: Bearer $CUTPRO_API_KEY"
```

Chave ausente, revogada ou vencida responde `401`:

```json title="401 Unauthorized"
{ "code": "UNAUTHORIZED" }
```

Conta bloqueada responde `403` com `ACCOUNT_BLOCKED`. Nesse caso nenhuma chave da conta funciona: fale com o suporte.

## Workspaces

Créditos, vídeos, clipes, renders e conexões pertencem a um workspace. A chave é vinculada a um ou mais workspaces, e cada requisição opera em exatamente um.

### Chave de um workspace

Nada a fazer. Toda requisição cai no workspace da chave.

### Chave com mais de um workspace

Mande `X-Workspace-Id` em toda requisição:

```bash
curl https://api.cut.pro/api/v1/balance \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "X-Workspace-Id: 7401220118845503"
```

Sem o header, a API responde `400` e lista os workspaces que a chave alcança:

```json title="400 Bad Request"
{
  "code": "MISSING_WORKSPACE_ID",
  "extra": { "allowed_workspace_ids": ["7401220118845503", "7401220118845991"] }
}
```

Um id fora dessa lista responde `400 WORKSPACE_NOT_AUTHORIZED`, com a mesma lista em `extra`.

Para saber em qual workspace a requisição caiu, com plano e papel, chame `GET /workspace`.

## Contas sociais

Para publicar, o workspace precisa de contas conectadas. `GET /connections` lista as que existem e devolve o `id` que vai em `connection_id` no post. Falta uma rede? `GET /connections/link?platform=tiktok` devolve um link da Cut.Pro que abre o login daquela rede. Entregue o link para a pessoa, espere ela voltar e liste de novo. Veja [Publicação](/publishing).

## Boas práticas

- **Uma chave por integração.** Se uma vazar, você revoga só ela.
- **Revogue o que não usa.** A página de chaves mostra cada chave, e revogar vale na hora.
- **Não logue o header.** Muitos clientes HTTP gravam headers em modo debug.