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

# Autenticação

> Obtenha uma chave de API para sua clínica odontológica, envie-a como token bearer, mantenha-a no seu servidor, faça a rotação ou a revogação e entenda cada erro de autenticação.

Toda requisição a `/v1` é autenticada com uma **chave de API**: uma credencial secreta de máquina que pertence a uma única clínica odontológica e tem uma lista explícita de [escopos](/docs/pt/api-reference/scopes). O endpoint MCP `/mcp` usa login e autorização com OAuth no Console.

## Como a chave é enviada

Envie a chave no cabeçalho `Authorization` com o esquema `Bearer`, em toda requisição:

```http theme={null}
GET /v1/me HTTP/1.1
Host: api.muveya.com
Authorization: Bearer mvy_test_EXAMPLE...
```

* A chave é uma string opaca, não um JWT. Não tente decodificá-la.
* `Authorization: Bearer` é o único transporte aceito. Não existe cabeçalho `X-API-Key` nem parâmetro de consulta para a chave.
* O nome do esquema não diferencia maiúsculas de minúsculas, mas a chave precisa ser enviada exatamente como foi emitida, sem aspas e sem quebras de linha.

## Como é uma chave

```text theme={null}
mvy_test_<24 letras e dígitos>_<4 letras e dígitos>
```

| Parte | Significado |
| - | - |
| `mvy` | O prefixo do muveya. Permite que os scanners de segredos reconheçam uma chave vazada. |
| `test` | O ambiente da chave. É o único ambiente emitido na v1 e **não** significa dados de teste: uma chave `mvy_test_` lê os dados reais da clínica odontológica à qual pertence. `GET /v1/me` o informa como `"environment": "test"`. |
| 24 caracteres | O segredo aleatório. |
| 4 caracteres | Um dígito verificador. Uma chave digitada errada ou incompleta é rejeitada antes de o muveya procurá-la. |

O muveya guarda apenas um hash SHA-256 da chave e seus primeiros 12 caracteres (o **prefixo**, por exemplo `mvy_test_ab1`). A chave completa é exibida uma única vez, na criação, e não pode ser recuperada depois. Se ela se perder, peça uma nova.

## Uma chave, uma clínica odontológica

Uma chave fica vinculada a uma clínica odontológica no servidor no momento da criação. Isso tem três consequências:

1. **Nenhuma requisição indica uma clínica odontológica.** Nenhum caminho, parâmetro ou cabeçalho de `/v1` aceita um id de tenant ou de espaço de trabalho. `GET /v1/me` informa qual clínica odontológica a chave lê, como `workspaceId`.
2. **Uma chave lê toda a clínica odontológica.** Ela não é limitada pelo acesso a unidades e depósitos que vale para os membros da equipe: dentro dos seus escopos, lê todas as unidades e todos os depósitos.
3. **Para integrar duas clínicas odontológicas, use duas chaves.** Um registro de outra clínica odontológica responde `404`, exatamente como se não existisse.

Uma chave não é uma pessoa. Ela não pode aprovar pedidos, confirmar entregas nem fazer nada que o produto reserva a um membro da equipe.

## Obter uma chave

<Warning>
  Ainda não existe uma tela no console para criar, listar ou revogar chaves de API. A equipe do muveya emite as chaves sob solicitação.
</Warning>

<Steps>
  <Step title="Peça a partir de uma conta que gerencia integrações">
    Um membro da sua clínica odontológica com a permissão **Gerenciar integrações e chaves de API** (`integrations.manage`) escreve para [team@muveya.com](mailto:team@muveya.com). Veja [Funções e permissões](/docs/pt/account/roles-and-permissions) para saber como essa permissão é concedida.
  </Step>

  <Step title="Diga para que serve a chave">
    Inclua um nome para a integração (por exemplo "Sincronização de estoque com o ERP") e os escopos exatos de que ela precisa. Escolha-os com as receitas de privilégio mínimo em [Escopos](/docs/pt/api-reference/scopes). Uma chave precisa ter pelo menos um escopo.
  </Step>

  <Step title="Guarde a chave assim que recebê-la">
    A chave é criada para esse membro e sua clínica odontológica, com exatamente os escopos que você pediu. Guarde-a imediatamente no seu gerenciador de segredos: ela é exibida uma única vez.
  </Step>

  <Step title="Verifique">
    Chame `GET /v1/me` (abaixo) e confirme que `workspaceId` e `scopes` são os esperados.
  </Step>
</Steps>

Regras que valem para toda chave:

| Regra | Valor |
| - | - |
| Escopos | Pelo menos um; veja [Escopos](/docs/pt/api-reference/scopes). Não é possível alterar os escopos de uma chave existente: peça uma chave nova. |
| Chaves ativas por clínica odontológica | No máximo 10 |
| Validade | As chaves emitidas hoje não têm data de expiração. Elas funcionam até serem revogadas ou até que ocorra uma das condições abaixo. |

### Quando uma chave deixa de funcionar

Uma chave só funciona enquanto o membro para quem foi criada continuar ativo na clínica odontológica:

* Se esse membro for **suspenso** ou **removido** da clínica odontológica, a chave para de funcionar imediatamente.
* **Reativar** o membro não traz a chave de volta. O console avisa isso ao reativar alguém: as chaves de API anteriores à suspensão continuam encerradas. Peça uma chave nova.
* Se a própria clínica odontológica estiver suspensa, todas as suas chaves são recusadas.

Peça as chaves a partir de um membro que continuará responsável pela integração, como um proprietário ou administrador que tenha a permissão **Gerenciar integrações e chaves de API** (nenhuma função a inclui).

## Sua primeira chamada: `GET /v1/me`

`GET /v1/me` não exige nenhum escopo. Use-a para verificar uma chave antes de qualquer outra coisa.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.muveya.com/v1/me \
    -H "Authorization: Bearer $MUVEYA_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.muveya.com/v1/me", {
    headers: { Authorization: `Bearer ${process.env.MUVEYA_API_KEY}` },
  });
  console.log(response.status, await response.json());
  ```

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

  response = requests.get(
      "https://api.muveya.com/v1/me",
      headers={"Authorization": f"Bearer {os.environ['MUVEYA_API_KEY']}"},
      timeout=30,
  )
  print(response.status_code, response.json())
  ```
</CodeGroup>

```json 200 OK theme={null}
{
  "workspaceId": "66d0a1f0c0ffee0000000001",
  "environment": "test",
  "scopes": ["clinics:read", "catalog:read", "inventory:read"]
}
```

<ResponseField name="workspaceId" type="string" required>
  A clínica odontológica à qual a chave pertence, definida pelo servidor.
</ResponseField>

<ResponseField name="environment" type="string" required>
  O ambiente da chave. Sempre `test` na v1.
</ResponseField>

<ResponseField name="scopes" type="string[]" required>
  Os escopos da chave, na forma com dois-pontos usada em toda a API (`catalog:read`).
</ResponseField>

A resposta nunca contém a chave, seu hash nem qualquer outro segredo.

## Mantenha as chaves no seu servidor

* Guarde a chave em um gerenciador de segredos ou em uma variável de ambiente do servidor, e leia-a em tempo de execução.
* Nunca a coloque em código de navegador, aplicativo móvel, planilha compartilhada, repositório de código, URL, linha de log ou relatório de erros.
* Use uma chave por integração, para poder revogar uma sem parar as outras.
* Quando falar com o suporte sobre uma chave, identifique-a pelo nome ou pelo prefixo (os primeiros 12 caracteres), nunca pela chave completa.
* Se uma chave pode ter vazado, peça a revogação imediatamente e substitua-a.

O construtor de requisições das páginas de **Endpoints** nunca envia requisições nem guarda sua chave, mas mesmo assim não cole uma chave em nenhuma página web.

## Rotacionar uma chave

<Steps>
  <Step title="Obtenha uma segunda chave">
    Peça uma chave nova com os mesmos escopos (veja [Obter uma chave](#obter-uma-chave)). As duas chaves funcionam ao mesmo tempo e ambas contam para o limite de 10 chaves ativas.
  </Step>

  <Step title="Implante-a">
    Substitua a chave antiga em todos os sistemas que a usam.
  </Step>

  <Step title="Verifique">
    Chame `GET /v1/me` a partir de cada sistema com a chave nova.
  </Step>

  <Step title="Revogue a chave antiga">
    Peça a revogação da chave antiga (abaixo).
  </Step>
</Steps>

## Revogar uma chave

Um membro com **Gerenciar integrações e chaves de API** (`integrations.manage`) escreve para [team@muveya.com](mailto:team@muveya.com) com o nome ou o prefixo da chave.

* A revogação vale a partir da próxima requisição. Não há cache para esperar.
* Não pode ser desfeita: uma chave revogada nunca volta a funcionar. Peça uma chave nova se ainda precisar de acesso.
* O registro da chave é mantido para a auditoria da sua clínica odontológica, assim como os eventos de criação e revogação.

## Respostas 401 e 403

| Status | `code` | Quando |
| - | - | - |
| `401` | `api_keys.invalid` | O cabeçalho `Authorization` está ausente, usa outro esquema ou está vazio; a chave está malformada ou o dígito verificador não confere; a chave é desconhecida ou foi revogada; o membro dela foi suspenso ou removido; ou a clínica odontológica dela está suspensa. |
| `403` | `api_keys.scope_missing` | A chave é válida, mas não tem um escopo que a operação exige. |

```json 401 Unauthorized (Accept-Language: pt) theme={null}
{
  "type": "https://docs.muveya.com/errors/api_keys.invalid",
  "title": "API key inválida",
  "status": 401,
  "detail": "A API key está ausente, é inválida, foi revogada ou expirou. Envie uma key válida como token Bearer e tente novamente.",
  "instance": "/v1/me",
  "code": "api_keys.invalid",
  "requestId": "8d0e5b8a-2f4c-4e1b-9a7d-0c3b5e6f7a81"
}
```

* O `401` é idêntico para todas as causas, de propósito: ele não revela se uma chave existe. Confira primeiro o formato do cabeçalho e depois verifique com o membro que pediu a chave se ela foi revogada ou se esse membro continua ativo.
* O `403` não diz qual escopo está faltando. Chame `GET /v1/me`, compare os `scopes` com a tabela em [Escopos](/docs/pt/api-reference/scopes) e peça uma chave com os escopos certos.
* Requisições recusadas com `401` ou `403` não consomem seu orçamento de [limites de uso](/docs/pt/api-reference/rate-limits) e não trazem cabeçalhos de limite.
* Um registro que pertence a outra clínica odontológica responde `404`, nunca `403`.

A lista completa de códigos está em [Erros](/docs/pt/api-reference/errors).

## O MCP usa OAuth

Uma chave de API não autentica `https://api.muveya.com/mcp`. Conecte um cliente MCP pelo [login e autorização no Console](/docs/pt/mcp/connect).


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