Portale di sviluppo e token di accesso

1) Ruolo del portale di sviluppo

Il portale Developer è un'fronte-ufficio "per gli integratori: servizio autonomo (chiavi, token, webhook, piani tariffari), trasparenza (limiti, usage, fatture), sicurezza (rotazione, firme), velocità di integrazione (SDK, documentazione, sabbia).

• Riduce TTI (time-to-integrate) a ore.
• Dà la maneggevolezza dell'accesso: chi/cosa/quanto/quando.
• Ridurre il carico di supporto tramite strumenti automatici.

2) Onboording e account

Registrazione: email + 2FA/SSO (SAML/OIDC); Conferma dominio (token DNS).
Organizzazioni e comandi: ruoli Owner, Ammin, Developer, Billing, Security.
Multi-tenant: allinea le applicazioni alle organizzazioni Accesso ai dati per tenente/ambiente.
KYC/B2B (opz.) Per Enterprise - persona legale, contratto, limiti più alti.

3) Allegati e crediti

Tipi di applicazioni: server-to-server, web, mobile, machine-to-machine, webhook-consumer.

3. 1 API Keys (server-to-server, semplici integrazioni)

ID «key _ id» + segreto «key _ secret» (visibile una volta).
Aggancia il piano e i set scopes.
Firma query (HMAC) e/o intestazione «Authorization: ApiKey <key _ id>: <firma>».

3. 2 OAuth2/OIDC (raccomandato)

• Client Credentials (macchine).
• Authorization Code (+PKCE) (user-delegated).
• Refresh Token (accesso offline, rotazione RT).
• Device Code (TV/console).

3. 3 mTLS (livello supplementare)

TLS reciproco su ingress; i certificati vengono scaricati tramite il portale il riferimento cert _ fingerprint all'applicazione.

4) Token: tipi e ciclo di vita

• AT + RT lungo; RT - rotazione slittante (rotate-on-use).
• Revoke (revoke) per chiave/applicazione/organizzazione.
• Rilascio pere con restrizioni scopes/quote.

4. 1 Formato JWT (esempio)

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..."
}

Le chiavi pubbliche sono pubblicate in JWKS; rotazione «kid».

4. 2 Opique token e Introspection

Memorizza nel server Auth «token _ store» (Redis/SQL).
Introspezione: «active», «scope», «exp», «client _ id», «org», «tenant».

5) Scopes, ruoli e criteri di accesso

Scopes descrive le operazioni ('wallet: read', 'wallet: write', 'report: read').
I ruoli vengono aggregati con scopes ('Developer', 'Billing').
ABAC: attributi «org», «tenant», «region», «environment».
Criteri: «Questa chiave è solo» eu-west-1 «e» read «».
Step-up - I metodi critici richiedono scopes o mTLS avanzate.

6) Quote, limiti e tariffe

Rate limits: RPS/RPM, burst.
Quote: giorno/mese, prestiti.
Per chiave/applicazione/organizzazione/tenante.
Il portale mostra l'usage, le intestazioni «X-RateLimit -» e «X-Quote» e la previsione overage.
Il bollo è collegato al piano, il metering per eventi, fatture e webhoop.

7) Gestione dei webhoop

Registrazione di endpoint, segreti, versioni di eventi.
Test di consegna e replay; logi di tentativo (2xx/4xx/5xx).
Etichette HMAC, X-Webhook-Id, deduplicazione, respect «410».

8) Documentazione e SDK

OpenAPI/AsyncAPI con la generazione di SDK.
Cookbook: esempi di query, retrai, idempotenza, paginazione, webhooks.
Try-it playground (con chiavi di sabbia).
Changelog Version e pagina di deprecazioni.

9) Sabbia e dati di prova

Ambienti isolati: sandbox, staging, produzione.
Entità di prova (giocatori, transazioni) e script (win/lose, ritardi, 5xx, 429).
Data seeding dal portale e reset dell'ambiente.

10) Sicurezza e conservazione dei segreti

Hash dei segreti API Key (non conservare in pubblico); Mostra la chiave una volta sola.
Gestione dei segreti (KMS/HSM) per i token della firma; rotazione delle chiavi «kid».
IP allowlist, vincoli geo, filtri ASN.
2FA/SSO, chiavi hardware (WebAuthn).
Protezione anti-abyuse: CAPTCHA quando si crea, euristica anti-bot, velocità di registrazione.
Loghi senza PII/segreti; redaction in base ai modelli.

11) Controllo e conformità

Loga di controllo: chi ha creato/visualizzato/ritirato la chiave, ha modificato il webhook, ha scaricato il rapporto.
GDPR/DSAR - Carica e rimozione dei dati dell'applicazione/organizzazione.
Criteri di conservazione: TTL per i fogli, Legale Hold per gli incidenti.
Terme of Use/Fair Use e vincoli di esportazione.

12) Amministrazione e operazioni

Recensione massiccia di token su un incidente/compromissione.
Sospensione temporanea dell'applicazione con causa e appello.
Roll-over chiavi (modalità a due righe: «active/next»).
Incidente-comm: stato-pagina, mailing, RSS/webhoop dello stato.

13) Portale UI/UX (schermate chiave)

Dashboard dell'organizzazione: usage/errori/sLO/billing.
Applicazione: chiavi, token, scopes, limiti, webhoop, ambiente.
I loghi di spedizione dei siti Web con filtri e il pulsante Replay.
Console token: rilascio/recensione, cronologia, motivi.
Documentazione e SDK, Quickstart, esempi di codice (copia-incolla).
Sezione «Deprecazioni e migrazioni».

14) Esempi di contratti e configure

14. 1 OpenAPI (sezioni)

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 Introspezione token (risposta)

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 Criteri chiavi (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) Processi di versioning e deprecazione

API semantica ('/v1 ', '/v2'), compatibilità «aggiungi, non rompere».
Il portale mostra «cosa è obsoleta», fino a che data e «come migrare».
Guide di migrazione, test di sabbia v2, dual-write/dual-read dove possibile.

16) Osservazione e segnalazione

I ricavi Usage sono i grafici delle richieste/crediti/overyge.
Errori di stato/' error _ code ', istogramma di latitanza.
Widget SLO: disponibilità e p95 per le maniglie chiave.
Esportazione CSV/JSON, report web, API per gli analisti.

17) Assegno fogli

17. 1 Sicurezza

• 2FA/SSO, conferma dominio/posta
• Visualizzazione dei segreti una volta, hash-storage
• JWKS e rotazione chiavi, 'kid'
• mTLS (opz.) , IP allowlist, filtri geo/ASN
• Anti-bot/anti-abuse, rate-limit per la creazione di chiavi
• Controllo-elenco delle attività e delle disponibilità

17. 2 DX/Onboarding

• Quickstart 5 minuti
• SDK (TS/Py/Java/Go/.NET) con la stessa superficie
• Playground + chiavi di sabbia
• Cookbook: webhook, paginazione, retrai, idimpotenza
• Pagina dei limiti/piani/prezzi
• Esempi di copia-incolla

17. 3 Operazioni

• Richiamo di massa dei token, aspend app
• Pagina incidenti/stato + sottoscrizione
• DLQ/Replay per webhoop
• Avvisi auto per l'esaurimento ravvicinato delle quote
• Report e fatture mensili

18) Piano di implementazione (3 iterazioni)

• Registrazione org/applicazioni, rilascio di API Keys, Client Credentials OAuth2, limiti di base (RPS/quote), fogli di query e grafica usage, documentazione e SDK TS/Python, cassetta di sabbia.

• JWT + JWKS, rotazione delle chiavi, Refresh Token + rotate-on-use, mandato 2FA/SSO, webhook (firme, retries, loging, replay), browser, report ed esportazione, ruoli e ABAC.

• utensili admine (mass revoke/suspend), deprecazioni e migrazioni v2, SDK Java/Go/.NET, finops-dashboard, GDPR/DSAR, Legale Hold, avanzata anti-abuse.

19) Mini FAQ

JWT o opache?
JWT è utile senza richiedere il server Auth (firma/' kid '), opique è più facile da richiamare e nascondere il contenuto. Spesso usano entrambi, in apparenza JWT, introspettiva.

Quanto vive Access Token?
Breve: 5-15 minuti per gli utenti, 15-60 minuti per le macchine. Compensato dalla meccanica refresh.

Come faccio a rotare le chiavi in modo sicuro?
Tenete «active/next», pubblicate entrambi su JWKS, scambiate i clienti in «kid», quindi richiamate il vecchio.

Totale

Un portale di sviluppo forte è l'autosufficienza, l'osservabilità e la sicurezza predefinite. Fornire processi chiari di rilascio/rotazione/ritiro dei token, limiti trasparenti e bollo, documentazione di qualità e SDK, siti web affidabili e verifiche. Gli integratori partiranno rapidamente e la piattaforma rimarrà gestibile, complessa e resistente al carico.