Portal de desenvolvedores e tocadores de acesso

1) Papel do portal de desenvolvimento

Developer Portal é um «frente-escritório» para integradores: serviço autônomo (chaves, tokens, webhooks, planos de tarifas), transparência (limites, usage, faturas), segurança (rotação, assinaturas), velocidade de integração (SDK, documentação, caixa de areia).

• Reduzir o TTI (time-to-integrate) para horas.
• Dar a governabilidade de acesso: quem/o/quanto/quando.
• Reduzir a pressão de suporte com ferramentas automáticas.

2) Contabilidade e contas

Inscrição: email + 2FA/SSO (SAML/OIDC); confirmação de domínio (token DNS).
Organizações e comandos: «Owner», «Admin», «Developer», «Billing», «Security».
Multi-tenante: vinculação de aplicativos a organizações; acesso aos dados pelo tenante/ambiente.
KYC/B2B (opz.) : para a Enterprise - pessoa jurídica, contrato, limites mais altos.

3) Aplicativos e empenhos

Os tipos de aplicativos são 'server-to-server', 'web', 'mobile', 'machine-to-machine', 'webhook-consumer'.

3. 1 API Keys (server-to-server, simples integrações)

ID de 'key _ id' + segredo 'key _ secret' (visto uma vez).
Vincular a um plano e a um conjunto de scopes.
Legenda de solicitação (HMAC) e/ou cabeçalho 'Autentication: ApiKey <key _ id>: <score>'.

3. 2 OAuth2/OIDC (recomendado)

• Cliente Credentals (máquinas).
• Authorization Code (+PKCE) (user-delegated).
• Refresh Token (acesso offline, rotação RT).
• Data Device (TV/console).

3. 3 mTLS (nível superior)

TLS mútuo no ingress; os certificados são baixados através do portal; vinculação 'cert _ fingerprint' ao aplicativo.

4) Tokens: tipos e ciclo de vida

• Curto AT + RT longo; RT - rotação deslizante (rotate-on-use).
• Revoque (revoke) por chave/aplicativo/organização.
• Emissão com limites de scopes/quotas.

4. 1 Formato JWT (exemplo)

json
{
"iss":"https://auth. example. com",
"sub":"app_123",
"aud":"https://api. example. com",
"exp":1730616000,
"iat":1730612400,
"scp":["wallet:read","bet:write"],
"org":"acme",
"kid":"jwks_2025_11",
"jti":"at_01HXY..."
}

As chaves públicas são publicadas na JWKS; rotação por 'kid'.

4. 2 Tocas Opaque e Introspation

Guarde no servidor Auth 'tocen _ store' (Redis/SQL).
Introspecção: «ativo», «scope», «exp», «cliente _ id», «org», «tenant».

5) Scopes, papéis e políticas de acesso

Os scopes descrevem as operações ('wallet: read', 'wallet: write', 'relatório: read').
Os papéis são agregados por scopes ('Developer', 'Billing').
ABAC: atributos «org», «tenant», «region», «ambiente».
Políticas: «Esta chave é apenas 'eu-west-1' e 'read'».
Step-up: os métodos críticos exigem scopes ou mTLS avançados.

6) Quotas, limites e tarifas

Rate limits: RPS/RPM, burst.
Quotas: dia/mês, empréstimos.
Por chave/aplicativo/organização/tenante.
O portal exibe usage, manchetes 'X-RateLimit' e 'X-Cota-', bem como previsão de overage.
Billing, ligação com o plano, metering de eventos, faturas e webhooks.

7) Gerenciamento de webhooks

Registro de endpoint's, segredos, versões de eventos.
Teste de entrega e replay; logs de tentativa (2xx/4xx/5xx).
Assinaturas HMAC ('X-Mensagem'), 'X-Webhook-Id', Deduplicação, respect '410'.

8) Documentação e SDK

OpenAPI/AsyncAPI com a geração de SDK.
Cookbook: exemplos de consultas, retraias, idempotidade, paginação, webhooks.
Try-it playground (com chaves de areia).
Changelog de versões e página de despreceção.

9) Caixa de areia e dados de teste

Ambientes isolados: «sandbox», «staging», «producition».
Entidades de teste (jogadores, transações) e cenários (win/lose, atrasos, 5xx, 429).
Data seeding do portal e reset do ambiente.

10) Segurança e armazenamento de segredos

Hash segredos de API Key (não armazenar em aberto); mostrar a chave uma vez.
Gerente de segredos (KMS/HSM) para os tokens de assinatura; rotação de chaves 'kid'.
IP allowlist, limitações geo, filtros ASN.
2FA/SSO, chaves de hardware (WebAuthn).
Protecção contra abyuz: CAPTCHA ao criar, avristas anti-bot, velocidade de registo.
Logs sem PII/segredos; redação por modelos.

11) Auditoria e conformidade

Verifiquei quem criou/reviu/retirou a chave, alterou o webhook, baixou o relatório.
GDPR/DSAR: descarga e remoção de dados do aplicativo/organização.
Políticas de armazenamento: TTL para logs, Legal Hold para incidentes.
Terms of Use/Fair Use e restrições de exportação.

12) Administração e operações

Um levantamento em massa sobre um incidente/comprometimento.
Suspensão temporária do aplicativo (suspend) com motivo e recurso.
Chave roll-over (modo de dois pontos: 'ativo/next').
Incidente-comm: página de status, e-mails, RSS/webhooks de status.

13) UI/UX do portal (telas-chave)

Dashboard organização: usage/erros/SLO/billing.
Aplicação: chaves, tocas, scopes, limites, webhooks, ambientes.
Logs de entrega de webhooks com filtros e botão Replay.
Console de Tóquio: lançamento/revisão, história, razões.
Documentação e SDK, Quickstart, exemplos de código (copiar-colar).
Seção de Despistagem e Migração.

14) Exemplos de contratos e configs

14. 1 OpenAPI (fatias)

yaml paths:
/v1/apps:
post:
summary: Create app security: [{ oauth2: [admin:apps. write] }]
responses:
'201': { description: Created }
/v1/apps/{app_id}/keys:
post:
summary: Create API key (shown once)
responses:
'201': { description: Created }
/v1/oauth2/token:
post:
summary: Token endpoint (CC/AC)
responses:
'200': { description: Access token }
/v1/tokens/revoke:
post:
summary: Revoke access/refresh token responses:
'204': { description: Revoked }

14. 2 Introspecção de token (resposta)

json
{
"active": true,
"client_id": "app_123",
"scope": "wallet:read bet:write",
"org": "acme",
"exp": 1730616000,
"token_type": "access_token",
"jti": "at_01HXY..."
}

14. 3 Política de chaves (JSON)

json
{
"app_id":"app_123",
"plan":"pro-2025",
"scopes":["wallet:read","report:read"],
"limits":{"rps":50,"daily_requests":250000},
"regions":["eu-west-1"],
"ip_allow":["192. 0. 2. 0/24"]
}

15) Processos de versionização e depredação

Versões semânticas da API («/v1 », «/v2»), compatibilidade «adicione, não rompa».
O portal mostra «o que é obsoleto», até que data, e «como migrar».
Guias migratórios, caixa de areia 'v2', dual-write/dual-read onde possível.

16) Observabilidade e relatórios

Receita → Usage: gráficos de solicitação/crédito/overidge.
Erros de status/' erro _ código ', histogramas de latência.
Widgets SLO: disponibilidade e p95 para canetas-chave.
Exportar CSV/JSON, webhooks de relatórios, API para analistas.

17) Folhas de cheque

17. 1 Segurança

• 2FA/SSO, confirmação de domínio/correio
• Exibição de segredos uma vez, hash armazenamento
• JWKS e rotação de chaves, 'kid'
• mTLS (opz.) , filtros IP allowlist, geo/ASN
• Anti-bot/anti-abuse, rate-limit para criação de chaves
• Auditoria-regulação de ações e acessibilidade

17. 2 DX/Onboarding

• Quickstart ≤ 5 minutos
• SDK (TS/Py/Java/Go/.NET) com a mesma superfície
• Playground + chaves de areia
• Cookbook: webhooks, paginação, retais, idempotação
• Página de limites/planos/preços
• Exemplos de copiar-colar

17. 3 Operações

• Revisão em massa de tokens, suspend app
• Página de incidentes/status + assinatura
• DLQ/Replay para webhooks
• Aviso automático para esgotamento próximo de quotas
• Relatórios e faturas mensais

18) Plano de implementação (3 iterações)

• Registro de org/aplicativos, emissão de API Keys, Cliente Credentals OAUth2, limites básicos (RPS/quotas), logs de solicitação e gráficos usage, documentação e SDK TS/Python, caixa de areia.

• JWT + JWKS, rotação de chaves, Refresh Token + rotate-on-use, mandato 2FA/SSO, webhooks (assinaturas, retrias, loging, replay), websites billing, relatórios e exportação, papéis e ABAC.

• mTLS, ferramentas de admin (mass revoke/suspend), depredação e migração v2, SDK Java/Go/.NET, finops-dashboards, GDPR/DSAR, Legal Hold, anti-abuse avançado.

19) Mini-FAQ

JWT ou opaque?
O JWT é conveniente sem a solicitação do servidor Auth (assinatura/' kid '), opaque - mais fácil de revogar e esconder o conteúdo. Os dois costumam usar o JWT, o opaque interno com introspecção.

Quanto tempo vive a Access Token?
5-15 minutos para os usuários, 15-60 minutos para as máquinas. Compensado pela mecânica refresh.

Como rotar as chaves de forma segura?
Mantenha 'ative/next', publique ambos no JWKS, alterne os clientes por' kid ', depois retire o antigo.

Resultado

Um portal de desenvolvimento forte é auto-manutenção, observabilidade e segurança padrão. Forneça processos de lançamento/rotação/revogação de tokens, limites transparentes e billing, documentação de qualidade e SDK, webhooks confiáveis e auditorias. Então os integradores começam rapidamente e a sua plataforma permanece controlada, completa e sustentável sob carga.