Zenkaiverse Developer Docs

01 · Introduzione

Cos’è questo portal

Un’unica area da cui partire per integrare e testare l’accesso con myZenkai, senza rincorrere URL sparsi o checklist solo mentali.

Hub per gli strumenti

Punto di accesso per chi vuole integrare Login with myZenkai: meno attrito tra documentazione, test e configurazione dei client.

Pensato per essere chiaro

L’obiettivo è spiegare con calma cosa succede quando un’app usa myZenkai per identificare un utente, senza diluvi di jargon.

02 · Disponibile oggi

Cosa puoi fare ora

Tre blocchi funzionali che puoi usare subito nel portal in ambiente alpha.

Entrare con myZenkai

Flusso di login reale: l’utente entra con il proprio account e il portal lo riconosce come autenticato.

Registrare bot e client

Mantieni in un registry unico sia i bot self-hosted sia i client OAuth, con onboarding e policy distinti.

Usare strumenti avanzati

Playground PKCE per authorize URL, code verifier, code challenge e verifica rapida del percorso OAuth.

05 · Playground PKCE

Come funziona il Playground PKCE

Sezione tecnica dedicata allo strumento avanzato del portal per costruire, avviare e verificare il flow OAuth 2.0 con PKCE.

Cosa fa

Genera una coppia PKCE valida: code_verifier e code_challenge S256.
Compone l'authorize URL con endpoint, client ID, redirect URI, scope e state.
Prepara lo stesso contesto che il portal riusa nel login e nella callback.
Mostra uno snippet curl per il token exchange manuale.

Quando usarlo

Stai configurando un nuovo client OAuth e vuoi verificare subito redirect URI e scope.
Vuoi fare debug di un errore di login, callback o token exchange.
Vuoi confrontare il comportamento del provider con una richiesta costruita manualmente.
Ti serve uno strumento operativo tecnico, non un wizard semplificato.

1. Compila i parametri

Inserisci authorize endpoint, token endpoint, client ID, redirect URI e scope.

2. Rigenera PKCE

Il pulsante genera un nuovo code verifier casuale e il corrispondente code challenge con metodo S256.

3. Costruisci e avvia

Con Costruisci URL ottieni l'authorize URL finale. Con Apri flow avvii il login e torni sulla callback del portal.

Risultati attesi

Authorize URL completo con response_type=code, state e campi PKCE valorizzati.
La callback riceve code e state coerenti con il contesto salvato nel browser.
Il token exchange va a buon fine e il portal salva una sessione locale.
Lo snippet curl riflette gli stessi parametri mostrati nella UI.

Segnali che qualcosa non va

Redirect bloccato: la redirect URI non coincide con quelle autorizzate.
State mismatch: il contesto PKCE salvato nel browser non corrisponde piu al ritorno.
Token exchange fallito: code_verifier, endpoint o client ID non coincidono.
Scope inattesi o insufficienti: il client non ha le autorizzazioni che stai testando.

Procedura consigliata

Crea o aggiorna il client in Bots & Clients con redirect URI e scope necessari.
Apri Playground PKCE e verifica client ID e redirect URI.
Rigenera PKCE, poi costruisci l'authorize URL.
Avvia il flow, completa il login e controlla in callback l'esito del token exchange.
Se serve, ripeti l'exchange con lo snippet curl per un debug piu isolato.

03 · Bot vs Client

Due modelli diversi, stesso registry

Il portal deve supportare sia bot sia client, ma senza confondere runtime, security model e responsabilita operative.

Bot self-hosted

La piattaforma registra identity, token model, capability, rate limits e audit log.
Il codice del bot gira nel runtime dello sviluppatore, non nel vostro hosting gestito.
Il modello iniziale consigliato e Discord-style: developer-hosted ora, managed hosting eventualmente dopo.
Le primitive da fissare subito sono token rotation, revoke, firma HMAC, anti-replay, lifecycle e ambienti separati.

OAuth client trusted

Il focus e su redirect URI, scope, PKCE, trust policy e callback OAuth.
Non esiste una bot identity dedicata o un runtime applicativo governato dalla piattaforma.
Il test operativo passa dal playground PKCE e dal code exchange.
Le policy di sicurezza restano diverse da quelle dei bot, anche se il registry e condiviso.

Decisione consigliata

Il percorso piu pragmatico e un modello ibrido: ora bot developer-hosted, poi eventualmente hosting gestito come livello premium o facilitato. In questo modo differenzi bene bot e client fin dal registry senza prendere subito il carico operativo del code execution hosting.

04 · Bot MVP contract

Fondamenta tecniche da fissare ora

Per partire in stile Discord (developer-hosted) il bot deve avere un contratto minimo stabile: token lifecycle, policy, sicurezza API e audit.

Checklist minima obbligatoria

Token model: scopes, expiry, rotation interval, revoke status.
Permission model: intents e capabilities granulari per app.
API security: HMAC required, nonce TTL e timestamp skew anti-replay.
Rate limits: quota API per minuto per bot/app.
Environment separation: DEV, STAGING, PROD con toggle indipendenti.
Lifecycle: ACTIVE, SUSPENDED, DELETED.
Trusted clients: allowlist client esterni autorizzati.
Audit logs: eventi principali (create/update/revoke/suspend).

Dove lo configuri nel portal

Vai in Bots & Clients e crea una risorsa Bot self-hosted.
Apri Resource Information e compila il blocco Bot foundations (MVP).
Salva per persistere configurazione, lifecycle e policy di sicurezza del bot.
Usa questi campi come source of truth per SDK/API contract e provisioning backend.

04 · Flusso

Come funziona, in sintesi

Quattro passaggi che collegano richiesta dell’app, login utente, codice temporaneo e scambio con token.

L’app chiede myZenkai

Un’app o uno strumento esterno avvia il flow e chiede il permesso di identificare l’utente.
Accesso utente

L’utente entra con il proprio account myZenkai. Con client configurato correttamente, il percorso resta coerente.
Codice temporaneo

Dopo il login l’app riceve un codice temporaneo: da solo non basta per accedere ai dati protetti.
Scambio con token

L’app scambia il codice (con PKCE dove richiesto) e ottiene il token per completare il login in modo sicuro.

SDK · Quickstart

Integrazione developer: copia e incolla

Sezione pensata per partire subito: installazione SDK, login, callback e chiamate API con bearer token.

1) Installa e configura lo SDK

npm install @myzenkai/sdk

import { createMyZenkaiSdk } from "@myzenkai/sdk";

const sdk = createMyZenkaiSdk({
  clientId: "your_client_id",
  authorizeEndpoint: "https://europe-west1-myzenkai-c58ee.cloudfunctions.net/oauthAuthorize",
  tokenEndpoint: "https://europe-west1-myzenkai-c58ee.cloudfunctions.net/oauthToken",
  redirectUri: "https://your-app.example.com/callback",
  scope: ["openid", "profile:read", "email:read"]
});

2) Pulsante login (start flow)

document.getElementById("loginBtn")?.addEventListener("click", async () => {
  await sdk.startLogin();
});

Lo SDK genera in automatico state, code_verifier e code_challenge (PKCE), poi apre il flow.

3) Pagina callback (chiusura flow)

const result = await sdk.handleCallback();

if (!result.ok) {
  console.error(result.error, result.errorDescription);
} else {
  console.log("Auth ok", result.session);
  window.location.href = "/#dashboard";
}

La callback e obbligatoria nel flow OAuth: qui avviene il token exchange finale.

4) Sessione e API protette

const session = sdk.getSession();
if (!session) throw new Error("Utente non autenticato");

const res = await fetch(
  "https://europe-west1-myzenkai-c58ee.cloudfunctions.net/oauthClientsApi/api/clients",
  {
    headers: {
      Authorization: `Bearer ${session.tokenResponse.access_token}`,
      Accept: "application/json"
    }
  }
);

const data = await res.json();
console.log(data);

Checklist rapida integrazione

Registra il client nel portal con redirect URI esatta e scope consentiti.
Usa Authorization Code + PKCE (gia gestito dallo SDK).
Verifica sempre state in callback (gia gestito dallo SDK).
Conserva il token in modo sicuro e gestisci la scadenza expires_in.
Per debug rapido usa Playground PKCE e Callback.

Note tecniche SDK (runtime behavior)

I parametri OAuth riservati (client_id, redirect_uri, response_type, scope, state, code_challenge, code_challenge_method) non vengono sovrascritti da parametri extra.
Se il provider non restituisce un expires_in valido, lo SDK applica un fallback di sicurezza a 3600 secondi.
In callback, oltre allo stato HTTP, lo SDK valida anche il payload della token response e rileva errori applicativi nel body.
In caso di errori non recuperabili (provider error, state mismatch, token exchange/network error), il contesto di pending auth viene pulito automaticamente.

Dati utente rilasciati per scope (data minimization)

openid: identificatore utente (uid / subject) necessario per associare la sessione all'utente autenticato.
profile:read: nickname e profilePhoto.
email:read: email.
Se uno scope non e approvato, i campi relativi non vengono restituiti nella risposta token.

Raccomandazione: richiedi solo gli scope strettamente necessari e mostra sempre all'utente finale perche ogni permesso e richiesto.

SDK · Error handling

Mappa errori e risoluzione

Chiavi errore attualmente restituite dal flow OAuth (SDK + endpoint backend), con tipo, motivo di ritorno e azione consigliata.

Come leggere gli errori

Controlla sempre error (chiave stabile) e error_description (dettaglio runtime).
In callback browser, usa il risultato di sdk.handleCallback(): result.error + result.errorDescription.
Su API HTTP OAuth, le risposte errore sono in JSON oppure nel redirect callback query string.
Per debug veloce, conserva URL authorize, payload token e configurazione client (redirect URI, origins, scope).

A) Errori callback SDK (`sdk.handleCallback()`)

invalid_callback · client-side validation · manca code o state nella callback URL · verifica redirect corretto e non aprire la callback manualmente.
missing_pending_auth · client-side state · contesto PKCE/state non presente in storage · rilancia startLogin() nello stesso browser/tab.
state_mismatch · client-side security · state ritornato non coincide con quello salvato · evita tab multiple e verifica che non ci siano redirect intermedi che alterano la query.
token_exchange_failed · server/token exchange · endpoint token ha risposto con errore HTTP o body applicativo in errore · leggi errorDescription e correggi client_id/redirect_uri/code_verifier/code.
invalid_token_response · server contract · risposta token senza access_token o token_type · verifica implementazione endpoint OAuth token.
network_error · network/CORS · fetch token fallita (CORS, DNS, TLS, offline) · controlla CORS origin, URL endpoint e rete.
[provider_error_passthrough] · provider redirect error · errore ricevuto direttamente da query callback (error + error_description) · usa la chiave provider ricevuta (es. invalid_request, access_denied) come root cause.

B) Errori endpoint authorize (`GET /oauthAuthorize`)

access_denied · oauth redirect error · il backend ha rifiutato la richiesta per policy/permessi (permission-denied) · controlla redirect URI autorizzata, origin consentita, scope consentiti, client abilitato, grants abilitati.
invalid_request · oauth redirect error · parametri mancanti/non validi o client non trovato (invalid-argument/not-found) · controlla client_id, redirect_uri, scope, response_type=code, PKCE (code_challenge).
invalid_request (JSON 400 fallback) · http error body · impossibile fare redirect verso callback valida · correggi callback URL e ripeti il flow.

C) Errori endpoint token (`POST /oauthToken`)

unsupported_grant_type · oauth token error · grant_type diverso da authorization_code · invia sempre authorization_code.
invalid_request · oauth token error · payload incompleto/non valido (es. campi mancanti) · invia client_id, code, redirect_uri, code_verifier.
invalid_grant · oauth token error · code non valido/scaduto/consumato, PKCE fallita, redirect mismatch, client mismatch · rigenera il flow completo e verifica coerenza tra authorize e token request.
server_error · oauth token error · errore interno inatteso · ritenta e consulta i log backend con dettaglio error_description.

D) Errori API protette portal (`/oauthApplicationsApi`, `/oauthClientsApi`)

unauthenticated · api auth error · bearer mancante/non valido/scaduto · invia Authorization: Bearer <access_token> valido.
permission_denied · api authorization error · token valido ma utente senza permessi sulla risorsa · usa client/application dell’owner corretto.
not_found · api resource error · route o risorsa inesistente · verifica path e identificatore risorsa.
invalid_request · api validation error · payload non conforme (es. appId/clientId/redirectUris/scope/origins) · correggi campi richiesti e formato.
server_error · api internal error · eccezione non mappata · ritenta e consulta logs funzione.

06 · Scope alpha

Su cos’è concentrato l’alpha

Cosa è già in pista e cosa non è ancora il focus del prodotto.

Già disponibile

Login with myZenkai nel portal
Registry base di bot self-hosted e client OAuth del proprietario
PKCE per test e integrazioni moderne
Playground per costruire e verificare il flow
Pagina callback per il ritorno OAuth

Non è il focus ora

Billing e piani commerciali
Analytics avanzate per app
Configurazioni enterprise complesse
Portale pubblico enorme multi-sezione
Documentazione esaustiva di ogni edge case

07 · Glossario

Termini ricorrenti

Definizioni brevi per orientarti nella UI e nelle guide.

Client

Profilo tecnico di un’app che usa myZenkai per il login: nome, identificatore e indirizzi autorizzati.

Redirect URI

Indirizzo a cui il browser torna dopo il login. Deve essere autorizzato in anticipo o il flow viene bloccato.

Scope

Tipo di accesso richiesto (es. identità di base, profilo pubblico, email).

PKCE

Protezione aggiuntiva per app pubbliche, CLI e client senza segreto server-side.

08 · Prossimi passi

Da qui in poi

Base pronta per guide operative: creare un client, configurare le redirect URI, capire gli scope e completare il code exchange con esempi mirati.

Torna al portal Apri il playground