Skip to main content

​
Monaco Protocol SDK v0.8.8

​
Breaking: authentication moves to ed25519 session-key signing

Authentication no longer uses JWT access/refresh tokens. The wallet now signs once to authorize a locally-generated ed25519 session key, and every request is signed with that key. All existing sessions are invalidated on deploy — every user must reconnect their wallet and sign once. Backend and frontend must deploy v0.8.8 together; there is no window where both auth schemes work. What changes for SDK users:
  • AuthState no longer has accessToken / refreshToken. It now carries sessionPublicKey, sessionPrivateKey, expiresAt, and user. The session private key is the credential — persist it (not a token) to restore a session without re-prompting the wallet.
  • sdk.login(clientId) is unchanged as the entry point and still returns AuthState. Request signing is automatic after login (and after sdk.setAuthState(...)); there is no token to attach.
  • The manual token methods sdk.auth.refreshToken(...) and sdk.auth.revokeToken() are gone. Use sdk.refreshAuth() (or sdk.auth.refreshSession()) to extend a session and sdk.logout() (or sdk.auth.revokeSession()) to revoke it.
  • React: useAuth exposes refreshSession / revokeSession (the old refreshToken / revokeToken are removed). The useTokenLifecycle hook and the provider tokenLifecycle prop now persist and refresh the session (keypair + expiry); their names and config are unchanged.
For direct REST users:
  • POST /api/v1/auth/challenge and POST /api/v1/auth/verify now require a session_public_key (64-char lowercase-hex ed25519 public key). verify no longer returns any tokens — only expires_at and user.
  • Every authenticated request must be signed with three headers: X-Monaco-PublicKey, X-Monaco-Timestamp (Unix milliseconds, within 30 seconds of server time), and X-Monaco-Signature. The signature covers METHOD\npath?query\ntimestamp_ms\nSHA256_hex(body).
  • POST /api/v1/auth/refresh and POST /api/v1/auth/revoke now take an empty body and are authenticated with those signing headers.
  • Backend services authenticate by sending their sk_ secret key in the x-server-key header on every request — there is no token exchange.
See TypeScript authentication and Authenticating Requests.

​
Added: custom API and WebSocket URLs

SDKConfig gains optional apiUrl and wsUrl overrides. When set, the core SDK (createMonacoSDK / new MonacoSDK) connects to the given URLs instead of the network preset’s defaults — useful for self-hosted deployments or CI/e2e stacks reachable only by a custom host (e.g. http://api-gateway:8080, ws://ws-api:8080/ws). network still selects the chain. Both must be valid absolute URLs or the constructor throws InvalidConfigError.

​
Upgrade