Configuracoes da conta

Tudo aqui fica sob /v1/settings. Ler exige o escopo settings:read; alterar, settings:write. Algumas operacoes exigem sessao do painel - uma pessoa logada - e recusam chave de API com 403: criar, revogar e rotacionar chaves, administrar a equipe, consultar a propria conta e trocar a propria senha. Se uma chave de API pudesse emitir outra chave ou criar um usuario, um vazamento viraria acesso permanente: quem revogasse a chave vazada encontraria outra no lugar.

Perfil da organizacao

curl -X PATCH http://localhost:3333/v1/settings/organization \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "legalName": "Minha Loja Ltda", "document": "11.222.333/0001-81", "timezone": "America/Sao_Paulo" }'

Envie so os campos que mudam; null apaga um campo opcional. Deslocamento como -03:00 e recusado no fuso de proposito: o PostgreSQL le esse formato com o sinal invertido, e o relatorio sairia seis horas fora do lugar sem erro nenhum. Cada alteracao vai para a auditoria com o valor anterior e o novo.

Chaves de API

O formato da chave e explicado em Primeiros passos: mk_<ambiente>_<prefixo>_<segredo>, presa a um ambiente. A chave vai no header Authorization: Bearer; o header X-Api-Key tambem e aceito.

curl -X POST http://localhost:3333/v1/settings/api-keys \
  -H "Authorization: Bearer $TOKEN_DA_SESSAO" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend de producao",
    "environment": "live",
    "scopes": ["payments:read", "payments:write", "customers:read", "customers:write"],
    "allowedIps": ["203.0.113.0/24"],
    "expiresAt": "2027-10-15T00:00:00.000Z"
  }'

• $TOKEN_DA_SESSAO e o accessToken de uma sessao do painel (POST /v1/auth/login): uma chave de API recebe 403 aqui.
• O segredo volta em secret uma unica vez. Guardamos apenas o hash: se perdeu, rotacione.
• Ninguem concede o que nao tem: pedir um escopo que a sua sessao nao possui responde 403.
• expiresAt e opcional (sem ele, a chave nao expira). Precisa estar ao menos 1 hora no futuro e no maximo 3 anos adiante.
• GET /v1/settings/api-keys lista as chaves de um ambiente (environment; padrao, o da credencial em uso), sem o segredo: prefixo, escopos, IPs, ultimo uso (lastUsedAt), expiracao, quem criou e a situacao (active, expired ou revoked). status=active mostra so as que autenticam agora.

Escopos

Conceda a cada chave so o que a integracao usa. Rota sem o escopo responde 403 com a lista do que falta.

Lista de IPs permitidos

allowedIps aceita ate 50 entradas: IPv4 (203.0.113.10), faixa IPv4 em CIDR (203.0.113.0/24) ou IPv6 exato. Lista vazia aceita qualquer origem. Fora da lista, a requisicao responde 403 com ip_not_allowed.

IPv4 isolado e gravado como /32, para casar tambem quando o servidor enxerga o cliente no formato IPv6 (::ffff:203.0.113.10). Faixa IPv6 (CIDR) ainda nao e aceita.

Revogar

curl -X POST http://localhost:3333/v1/settings/api-keys/key_01HQ.../revoke \
  -H "Authorization: Bearer $TOKEN_DA_SESSAO" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Servidor desativado" }'

A chave para de autenticar na hora: a proxima chamada recebe 401 com api_key_revoked. O motivo (ao menos 3 caracteres) fica na chave e na auditoria. Chave expirada responde 401 com token_expired.

Rotacionar sem parar a integracao

curl -X POST http://localhost:3333/v1/settings/api-keys/key_01HQ.../rotate \
  -H "Authorization: Bearer $TOKEN_DA_SESSAO" \
  -H "Content-Type: application/json" \
  -d '{ "graceHours": 24, "reason": "Rotacao periodica" }'

A rotacao cria a substituta com o mesmo nome, ambiente, escopos e IPs, e devolve o segredo dela uma unica vez. A validade da nova tem a mesma duracao da antiga: rotacionar uma chave de 90 dias rende outra de 90 dias.

• graceHours (0 a 168, padrao 24) e o tempo em que a antiga continua autenticando, para voce trocar a variavel de ambiente sem parar de cobrar. rotatedFrom.validUntil diz ate quando. Se a antiga expiraria antes, vale a expiracao dela.
• graceHours: 0 revoga a antiga na hora. Use em suspeita de vazamento.
• Chave revogada, expirada ou ja rotacionada nao pode ser rotacionada (409): rotacione a nova, ou crie outra.

Limite por minuto

rateLimitPerMinute e aceito na criacao, gravado e devolvido na listagem, mas ainda nao e aplicado: e uma configuracao reservada. Nenhuma requisicao e recusada por ela hoje.

Equipe e papeis

Cada pessoa da equipe tem um papel, e o papel define os escopos da sessao dela no painel. A troca de papel vale na proxima requisicao: os escopos sao recalculados a cada chamada.

GET /v1/settings/roles devolve a tabela exata de escopos de cada papel - a mesma usada na autorizacao. "Alterar pagamentos" e o escopo payments:write, que inclui capturar, cancelar e estornar.

O convite e a nova senha devolvem uma senha temporaria uma unica vez, para o administrador repassar - nao ha envio de e-mail. A pessoa troca a senha no primeiro acesso; enquanto isso, passwordChangeRequired vem true.

Regras que protegem a conta:

• So um proprietario concede, altera ou desativa outro proprietario.
• Ninguem altera o proprio papel nem desativa a si mesmo por aqui.
• Sempre resta ao menos um proprietario ativo: rebaixar ou desativar o ultimo responde 409.
• Rebaixar (perder qualquer escopo, ou deixar de ser proprietario) encerra as sessoes do membro.
• Cada e-mail entra em uma unica organizacao.

O status de cada membro e active, invited (nunca entrou), locked (bloqueado por tentativas) ou inactive.

Sua conta e seguranca

• GET /v1/settings/account mostra o membro da sessao atual, com os escopos.
• POST /v1/settings/account/password troca a propria senha. Exige a senha atual, aninhada em password.current e password.next, e encerra todas as sessoes, inclusive a atual.
• GET /v1/settings/security mostra a politica em vigor: senha de no minimo 12 caracteres, bloqueio apos 5 tentativas erradas por 15 minutos e a duracao das sessoes. Os papeis owner e admin sao marcados como exigindo MFA, mas o cadastro de MFA ainda nao esta disponivel (enrollmentAvailable: false).

Auditoria

GET /v1/settings/audit-logs lista as acoes administrativas da organizacao, da mais recente para a mais antiga. A trilha e append-only: nao ha como alterar nem apagar um registro.

curl "http://localhost:3333/v1/settings/audit-logs?action=api_key.&from=2026-10-01T03:00:00Z" \
  -H "Authorization: Bearer $MINSTREL_API_KEY"

Cada registro traz quem fez (actor: pessoa, chave de API ou o sistema), o recurso com um nome legivel (resource.label), as mudancas em changes - com segredos sempre mascarados -, IP, user agent e o requestId da chamada.

A trilha e da organizacao, nao do ambiente: uma chave de producao revogada por alguem no sandbox aparece do mesmo jeito.