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

# Introdução

> Chaves de API autenticam suas requisições e definem o alcance de cada aplicação — entenda os tipos de chave, os limites de uso, a revogação e as boas práticas.

# Administrando API Keys

A segurança é um pilar fundamental da API MessageFy. **Toda requisição é autenticada por uma chave
de API** — um token único que identifica sua aplicação e autoriza o acesso aos endpoints.

Cada chave vive dentro de uma [*Account*](/contas/introducao) específica e só pode acessar os
recursos daquela *Account* — esse isolamento é o que permite operar múltiplos departamentos ou
clientes com segurança em uma mesma *organization*.

## Para que serve uma API Key?

<AccordionGroup>
  <Accordion title="Autenticação Segura">
    Toda requisição deve incluir uma API Key válida no header `X-API-KEY`. Sem ela, a requisição é
    rejeitada com `401 Unauthorized`.
  </Accordion>

  <Accordion title="Abrangência definida pelo tipo da chave">
    O alcance de uma chave é determinado pelo seu **tipo**, indicado no prefixo do token: `org_`
    abrange toda a *organization*; `acc_` fica restrita a uma única *Account*. Não existem permissões
    por *scope* — a segregação acontece pela combinação de tipo da chave e isolamento por *Account*.
  </Accordion>

  <Accordion title="Limite de uso (rate limit)">
    Cada chave está vinculada a um **resource plan**, que define o limite de requisições por janela
    de tempo (`limit` requisições a cada `seconds` segundos). É esse plano — e não um conjunto de
    permissões — que controla a intensidade de uso da chave.
  </Accordion>

  <Accordion title="Rastreabilidade e Auditoria">
    Cada chave tem um identificador único, e todas as requisições são registradas. Você consegue
    saber exatamente qual chave foi usada em cada ação — fundamental para auditoria de segurança e
    investigação de incidentes.
  </Accordion>

  <Accordion title="Revogação Instantânea">
    Se uma chave for comprometida, revogue-a imediatamente sem afetar as demais. Bem mais seguro do
    que compartilhar uma única credencial entre múltiplas aplicações.
  </Accordion>

  <Accordion title="Segregação de Ambientes">
    Mantenha chaves distintas para desenvolvimento, *staging* e produção, cada uma com permissões e
    configurações apropriadas ao ambiente.
  </Accordion>
</AccordionGroup>

## Tipos de chave

A chave de API tem seu tipo indicado pelo **prefixo** do token:

| Prefixo | Tipo        | Escopo                                       |
| ------- | ----------- | -------------------------------------------- |
| `org_`  | Organização | Acessa todas as *Accounts* da *organization* |
| `acc_`  | Conta       | Acessa somente a *Account* que a emitiu      |

Esse nível de acesso é exposto no campo `type` do retorno da chave, ao lado do plano de recursos
que rege o rate limit:

<ResponseField name="type" type="string">
  Nível de acesso da chave. Reflete o prefixo do token (`org_` para toda a *organization*, `acc_`
  para uma única *Account*) e substitui qualquer noção de *scopes*.
</ResponseField>

<ResponseField name="resourcePlan" type="object">
  Plano de recursos vinculado à chave, que define o **rate limit**.

  <ResponseField name="limit" type="integer">
    Número máximo de requisições permitidas dentro da janela.
  </ResponseField>

  <ResponseField name="seconds" type="integer">
    Duração da janela, em segundos (`limit` requisições a cada `seconds` segundos).
  </ResponseField>
</ResponseField>

<Tip>
  Use o endpoint [`/me`](/api-reference/me) para descobrir o tipo e as características da chave em
  uso — útil para validação inicial em pipelines de integração.
</Tip>

## Como usar

Inclua a chave no header `X-API-KEY` de toda requisição:

```bash theme={null}
curl -X POST https://api-dev.messagefy.io/api/v1/message/SendMessage \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: sua-api-key-aqui" \
  -d '{ ... }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://api-dev.messagefy.io/api/v1/message/SendMessage",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "sua-api-key-aqui",
    },
    json={...},
)
```

```javascript Node.js theme={null}
const response = await fetch(
  "https://api-dev.messagefy.io/api/v1/message/SendMessage",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": "sua-api-key-aqui",
    },
    body: JSON.stringify({ /* ... */ }),
  }
);
```

## Operações disponíveis

<CardGroup cols={2}>
  <Card title="Listar API Keys" icon="list" href="/api-reference/listar-api-keys">
    Lista as chaves emitidas para a *Account* atual, com filtros e paginação.
  </Card>

  <Card title="Buscar por ID" icon="magnifying-glass" href="/api-reference/obter-api-key">
    Recupera os detalhes de uma chave específica (sem expor o token).
  </Card>

  <Card title="Criar API Key" icon="plus" href="/api-reference/criar-api-key">
    Gera uma nova chave. O token só é exibido **uma vez** — copie-o no momento da criação.
  </Card>

  <Card title="Atualizar API Key" icon="pen" href="/api-reference/atualizar-api-key">
    Atualiza o nome e a descrição da chave. Não há ativar/desativar — para revogar, use a exclusão.
  </Card>

  <Card title="Revogar API Key" icon="trash" href="/api-reference/deletar-api-key">
    Revoga permanentemente o acesso de uma chave.
  </Card>

  <Card title="Sobre a chave atual" icon="key" href="/api-reference/me">
    Endpoint `/me` para inspecionar a chave usada na requisição.
  </Card>
</CardGroup>

## Boas práticas

<AccordionGroup>
  <Accordion title="Trate API Keys como senhas">
    Não exponha chaves em código *client-side*, repositórios públicos ou logs. Use variáveis de
    ambiente ou um cofre de segredos (Vault, AWS Secrets Manager, etc.) no servidor.
  </Accordion>

  <Accordion title="Crie chaves distintas por aplicação">
    Uma chave por aplicação (ou por instância, em casos sensíveis). Isso granulariza o acesso,
    facilita auditoria por origem e permite revogação cirúrgica em caso de comprometimento.
  </Accordion>

  <Accordion title="Escolha o tipo de chave mais restrito">
    Prefira chaves `acc_`, restritas a uma única *Account*, sempre que a aplicação não precisar
    operar toda a *organization*. Reserve chaves `org_` para integrações que realmente exigem alcance
    global — assim você limita o impacto de um eventual vazamento.
  </Accordion>

  <Accordion title="Separe ambientes (dev / stg / prd)">
    Use chaves diferentes em cada ambiente. Uma chave de produção nunca deve aparecer em código de
    desenvolvimento — e vice-versa.
  </Accordion>

  <Accordion title="Rotacione periodicamente">
    Mesmo sem suspeita de comprometimento, rotacione as chaves em intervalos regulares (90 dias é
    um bom ponto de partida). Mantenha as duas chaves ativas durante o período de transição.
  </Accordion>
</AccordionGroup>

<Warning>
  O **token completo** da chave só é retornado **na criação**. Depois disso, somente o ID e os
  metadados ficam acessíveis. Se você perder o token, terá que revogar a chave e criar uma nova.
</Warning>