Developer Portal and Access Tokens

1) Developer Portal Role

Developer Portal is a "front office" for integrators: self-service (keys, tokens, webhooks, tariff plans), transparency (limits, usage, invoices), security (rotation, signatures), integration speed (SDK, documentation, sandbox).

• Reduce TTI (time-to-integrate) to hours.
• Give access control: who/what/how much/when.
• Reduce the load on support through auto-tools.

2) Onboarding and accounts

Registration: email + 2FA/SSO (SAML/OIDC); Domain validation (DNS token).
Organizations and teams: 'Owner', 'Admin', 'Developer', 'Billing', 'Security' roles.
Multi-tenant: linking applications to organizations; data access - by tenant/environment.
KYC/B2B (wholesale) : for Enterprise - legal entity, contract, limits above.

3) Appendices and credits

Application types: 'server-to-server', 'web', 'mobile', 'machine-to-machine', 'webhook-consumer'.

3. 1 API Keys (server-to-server, simple integrations)

Identifier 'key _ id' + secret 'key _ secret' (visible once).
Binding to scopes plan and sets.
Request Signature (HMAC) and/or'Authorization: ApiKey <key_id>:<signature>' header.

3. 2 OAuth2/OIDC (recommended)

• Client Credentials (machines).
• Authorization Code (+PKCE) (user-delegated).
• Refresh Token (offline access, RT rotation).
• Device Code (TV/consoles).

3. 3 mTLS (additional level)

Mutual TLS on ingress; certificates are downloaded through the portal; binding 'cert _ fingerprint' to the application.

4) Tokens: types and lifecycle

• Short AT + long RT; RT - rotate-on-use.
• Revoke by key/application/organization.
• Re-issuance with scopes/quotas restrictions.

4. 1 JWT format (example)

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

Public keys are published in JWKS; rotation by 'kid'.

4. 2 Opaque tokens and Introspection

Store 'token _ store' (Redis/SQL) in the Auth server.
Introspection: 'active', 'scope', 'exp', 'client _ id', 'org', 'tenant'.

5) Scopes, roles and access policies

Scopes describe operations ('wallet: read', 'wallet: write', 'report: read').
Roles aggregate scopes ('Developer', 'Billing').
ABAC: attributes' org ',' tenant ',' region ',' environment '.

Politicians: "this key is only 'eu-west-1' and 'read'."

Step-up: Critical methods require extended scopes or mTLS.

6) Quotas, limits and tariffs

Rate limits: RPS/RPM, burst.
Quotas: day/month, credits.
By key/application/organization/tenant.
The portal shows usage, the headers' X-RateLimit- 'and' X-Quota- ', as well as the overage forecast.
Billing: linking with a plan, metering by events, invoices and billing webhooks.

7) Webhook management

Registration of endpoints, secrets, event versions.
Test delivery and replay; retry logs (2xx/4xx/5xx).
HMAC signatures ('X-Signature'), 'X-Webhook-Id', deduplication, respect '410'.

8) Documentation and SDK

OpenAPI/AsyncAPI with SDK auto-generation.
Cookbook: examples of requests, retrays, idempotence, pagination, webhooks.
Try-it playground (with sand keys).
Version Changelog and the page of depressions.

9) Sandbox and test data

Isolated environments: 'sandbox', 'staging', 'production'.
Test entities (players, transactions) and scripts (win/lose, delays, 5xx, 429).
Data seeding from the portal and reset environment.

10) Security and storage of secrets

API Key hash of secrets (do not store in clear text); show key once.
Secret Manager (KMS/HSM) for signature tokens; rotation of 'kid' keys.
IP allowlist, geo-constraints, ASN filters.
2FA/SSO, hardware keys (WebAuthn).
Protection against abuse: CAPTCHA when creating, anti-bot heuristics, registration speed.
Logs without PII/secrets; redaction by patterns.

11) Audit and Compliance

Audit log: who created/viewed/revoked the key, changed the webhook, downloaded the report.
GDPR/DSAR - download and delete application/organization data.
Retention policies: TTL for logs, Legal Hold for incidents.
Terms of Use/Fair Use and export restrictions.

12) Administration and Operations

Mass recall of tokens by incident/compromise.
Temporary suspension of the application (suspend) with cause and appeal.
Key roll over (two-key mode: 'active/next').
Incident comm: status page, mailings, RSS/webhooks status.

13) UI/UX portal (key screens)

Organization dashboard: usage/errors/SLO/billing.
Application: keys, tokens, scopes, limits, webhooks, environments.
Webhook delivery logs with filters and a Replay button.
Token console: issue/recall, history, reasons.
Documentation and SDK, Quickstart, code samples (copy-paste).

Section "Deprections and migrations."

14) Examples of contracts and configs

14. 1 OpenAPI (snippets)

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 Introspection token (answer)

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 Key Policy (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) Versioning and escrow processes

Semantic API versions ('/v1 ', '/v2'), add-do-not-break compatibility.

The portal shows: "what becomes obsolete," until what date, and "how to migrate."

Migration guides, test sandbox 'v2', dual-write/dual-read wherever possible.

16) Observability and reporting

Usage → revenue: request/credit/overlay schedules.
Errors by status/' error _ code ', latency histograms.
SLO widgets: accessibility and p95 for key handles.
Export CSV/JSON, webhooks of reports, API for analytics.

17) Checklists

17. 1 Safety

• 2FA/SSO, domain/mail confirmation
• Show secrets once, hash storage
• JWKS and key rotation, 'kid'
• mTLS (Ex) , IP allowlist, geo/ASN filters
• Anti-bot/anti-abuse, rate-limit on key generation
• Audit log of actions and accesses

17. 2 DX/Onboarding

• Quickstart ≤ 5 minutes
• SDK (TS/Py/Java/Go/.NET) with the same surface
• Playground + sand keys
• Cookbook: Webhooks, Pagination, Retreats, Idempotence
• Limits/Plans/Pricing Page
• Copy-paste examples

17. 3 Operations

• Mass token recall, suspend app
• Incident/Status Page + Subscription
• DLQ/Replay for Webhooks
• Auto-Alerts for Near Quota Exhaustion
• Monthly Reports and Invoices

18) Implementation plan (3 iterations)

• Registration of org/applications, issuance of API Keys, Client Credentials OAuth2, basic limits (RPS/quotas), request logs and usage graphs, documentation and SDK TS/Python, sandbox.

• JWT + JWKS, key rotation, Refresh Token + rotate-on-use, mandatory 2FA/SSO, webhooks (signatures, retries, logging, replay), billing webhooks, reports and exports, roles and ABAC.

• mTLS, admin tools (mass revoke/suspend), decrements and migrations v2, Java/Go/.NET SDK, finops dashboards, GDPR/DSAR, Legal Hold, advanced anti-abuse.

19) Mini-FAQ

JWT or opaque?
JWT is convenient without asking the Auth server (signature/' kid '), opaque is easier to revoke and hides the content. Both are often used: externally JWT, internally opaque with introspection.

How long does Access Token live?
Short: 5-15 minutes for custom, 15-60 minutes for machine. Compensated by refresh mechanics.

How to safely rotate keys?
Keep 'active/next', post both to JWKS, switch clients by 'kid', then recall the old one.

Total

A strong developer portal is self-service, observability, and security by default. Give clear processes for issuing/rotating/revoking tokens, transparent limits and billing, high-quality documentation and SDKs, reliable webhooks and audits. Then the integrators will start quickly, and your platform will remain manageable, compliant and stable under load.