Autenticação

​

Como a chave é enviada

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

mvy_test_<24 letras e dígitos>_<4 letras e dígitos>

​

Uma chave, uma clínica odontológica

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.

​

Obter uma chave

​

Quando uma chave deixa de funcionar

• 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.

​

Sua primeira chamada: GET /v1/me

curl https://api.muveya.com/v1/me \
  -H "Authorization: Bearer $MUVEYA_API_KEY"

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());

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())

{
  "workspaceId": "66d0a1f0c0ffee0000000001",
  "environment": "test",
  "scopes": ["clinics:read", "catalog:read", "inventory:read"]
}

​

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.

​

Rotacionar uma chave

​

Revogar uma 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

{
  "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 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 e não trazem cabeçalhos de limite.
• Um registro que pertence a outra clínica odontológica responde 404, nunca 403.

​

O MCP usa OAuth