MoraselA API do Morasel para desenvolvedores
Leia e aja sobre os mesmos registros que sua equipe usa — conversas, clientes, agendamentos, pedidos — com tokens que você delimita, restringe por IP e expira no seu próprio cronograma.
Por que uma chave sem escopo e sem expiração é um risco
Uma única chave de API sem escopo, sem restrição de IP e sem expiração é um risco permanente: se vazar, quem a encontrar pode ler ou gravar tudo que o espaço de trabalho permite. A maioria das integrações precisa só de uma fração desse acesso, por um período fixo, a partir de sistemas conhecidos.
- Um token com acesso total pode ler ou gravar registros que uma integração nunca precisou.
- Um token sem expiração ainda é válido um ano depois de o projeto que o criou ter terminado.
- Um token usável de qualquer IP pode ser reutilizado de qualquer lugar para onde o texto puro vazar.
- Uma chave cujo texto puro ninguém consegue mais recuperar não pode ser conferida, só revogada e substituída.
O que o Morasel registra de cada token
Um registro de token por integração, para um proprietário ver o que ele pode fazer e quando foi usado pela última vez sem perguntar à equipe que o criou.
- Nome do token
- O rótulo que sua equipe dá ao token, ligado à integração a que pertence.
- Prefixo
- Os primeiros caracteres do token, exibidos após a criação para identificá-lo sem o segredo.
- Escopos
- Os objetos e ações que o token alcança; leitura por padrão, escrita concedida por objeto.
- Lista de IP permitidos
- Até 20 endereços de onde o token pode ser usado; vazia significa sem restrição de IP.
- Expiração
- Uma data de até 365 dias após a qual o token para de funcionar.
- Último uso
- A hora mais recente em que uma requisição foi autenticada com esse token.
- Endpoint de webhook
- A URL e o segredo de assinatura que você registra no espaço de trabalho para sua integração.
De criar um token a rotacioná-lo
O segredo em texto puro existe uma vez, na criação. Tudo depois disso roda sobre o prefixo e os escopos que você definiu.
Crie um token (proprietário)
Dê um nome, escolha os escopos e, opcionalmente, defina uma lista de IP permitidos e uma expiração de até 365 dias.
Copie o segredo uma vez
O token completo é exibido uma única vez. Depois disso, só o prefixo fica visível no registro.
Chame a API REST com um cabeçalho Bearer
Autentique requisições contra os endpoints documentados; cada chamada é checada contra os escopos e a lista de IP do token.
Registre um endpoint de webhook e guarde seu segredo de assinatura
Adicione a URL do endpoint pelo espaço de trabalho e guarde o segredo de assinatura que ele fornece.
Rotacione: crie o sucessor, revogue o antigo
Emita um token novo antes que o antigo expire ou seja comprometido, e revogue o antigo assim que o novo estiver ativo.
O que o cliente vê
Uma mensagem enviada pela API parece exatamente com uma enviada do espaço de trabalho — o cliente não tem como diferenciar.
O que sua equipe vê
A atividade de um token é um registro, não um mistério nos logs.
- Os escopos, a lista de IP, a expiração e o último uso de cada token, num só registro.
- O endpoint de webhook e a opção de revelar ou rotacionar seu segredo de assinatura.
- Um prefixo para identificar um token numa conversa sem precisar do segredo de novo.
- Eventos de criação e revogação no mesmo registro de auditoria de tudo mais no espaço de trabalho.
Quem pode fazer o quê
Emitir e revogar acesso fica restrito a quem é proprietário do espaço de trabalho, e cada mudança fica registrada.
- Só um proprietário do espaço de trabalho pode criar ou revogar um token de API.
- Os escopos são de leitura por padrão; acesso de escrita a um objeto é concedido explicitamente, nunca presumido.
- Uma lista de IP permitidos, quando definida, limita um token a até 20 endereços conhecidos.
- Toda criação e revogação de token fica no registro de auditoria, com quem fez e quando.
O que o Morasel não faz
Endpoints de webhook são registrados com um segredo de assinatura a partir do espaço de trabalho. O Morasel não publica SDKs; a API REST é documentada como OpenAPI. Registrar um endpoint guarda a URL e o segredo de assinatura dele para a sua integração.
Comece a construir sobre o Morasel
Crie um espaço de trabalho, emita um token com escopo definido, e leia a referência OpenAPI dos endpoints que você precisa.
Perguntas de desenvolvedores
Como eu consigo um token?
Um proprietário do espaço de trabalho o cria por lá: nome, escopos e, opcionalmente, uma lista de IP permitidos e uma expiração. O texto puro é exibido uma vez na criação.
Quais escopos existem?
Acesso de leitura é o padrão. Acesso de escrita a um objeto específico — conversas, clientes, agendamentos, pedidos — é concedido por escopo, então um token só alcança o que foi feito para alcançar.
O que a lista de IP permitidos faz?
Restringe o token a até 20 endereços IP específicos. Deixe vazia e o token funciona de onde quer que o segredo seja usado; defina e requisições de outros endereços são rejeitadas.
Por quanto tempo um token pode durar?
Até 365 dias. Depois disso, ou na data que você definir, ele para de autenticar e precisa ser substituído.
Onde está a referência da API?
A API REST é documentada como OpenAPI em /docs, cobrindo os endpoints que os escopos de um token alcançam.