Integrate Hybrid-ID

Start here

Hybrid-ID is a self-hosted OpenID Connect identity provider. Your application redirects users to Hybrid-ID for sign-in and consent, validates the result on its backend, then creates its own application session. Hybrid-Chain is another application in the ecosystem; you do not need to integrate its trading, wallet or commerce systems to use Hybrid-ID.

• Register your application in Developer applications, or use the delegated developer API below. Account owners need an authenticator to create or change apps and agent credentials in the portal.
• Use a confidential web backend and Authorization Code with PKCE S256. Never embed a client secret in JavaScript, a downloadable game, Unity, a mobile app or a public repository.
• Store game profiles, progress and permissions in your application database. Use the stable pair (issuer, subject) to associate them with Hybrid-ID.
• Existing Hybrid accounts work. New Hybrid-ID account creation remains invitation-only; account access is separate from registering a developer application.

Register and manage your application

• Give the app a recognizable name and exact HTTPS callback URLs, for example https://game.example/auth/hybrid/callback. The consent page displays the callback origin as well as the app name.
• Configure optional post-logout redirect URLs. Up to five URLs of each kind are supported, all on one public HTTPS origin. No wildcard, fragment, query-string, localhost or IP callbacks. Use your own hostname.
• Create separate production and staging apps. The callback origin cannot change after creation because it determines the pairwise subject sector; paths on that origin can be edited.
• Save the generated client ID and client secret in the backend environment/secret manager. A secret is displayed only on creation or rotation. Rotation invalidates the old secret immediately.
• Disable an app to stop new sign-ins and invalidate provider grants. Disabling is permanent; local sessions already issued by your app need your own revocation handling.
• Current safety limits: 20 registrations per owner, 10 active agent credentials and 120 developer requests per owner per minute. These are operational limits, not paid subscription tiers.

HYBRID_ISSUER=https://auth.hybrid-id.com
HYBRID_CLIENT_ID=<your registered client ID>
HYBRID_CLIENT_SECRET=<server-only secret>
HYBRID_CALLBACK_URL=https://game.example/auth/hybrid/callback

Agent API: register without an interactive login

An owner signs in once to delegate access under Developer applications → Agent & automation access. The resulting hid_dev_ credential is a bearer credential valid for 30 days. Give it to your agent through a secure runtime secret store. Each API call then runs without a browser login. The agent cannot create more agent credentials, impersonate another owner or access user profiles. Revoke the credential in the portal to end its access.

GET and POST https://hybrid-id.com/api/developer/v1/applications accept Authorization: Bearer <developer credential>. POST requires application/json. This is a separate Hybrid-ID management API, not a Hybrid-Chain V2 route. OIDC app client secrets, user access tokens and Ed25519 signing keys cannot authenticate it.

curl https://hybrid-id.com/api/developer/v1/applications \
  -H "Authorization: Bearer $HYBRID_DEVELOPER_TOKEN"

curl https://hybrid-id.com/api/developer/v1/applications \
  -H "Authorization: Bearer $HYBRID_DEVELOPER_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"action":"create","name":"Example game","redirect_uris":["https://game.example/auth/hybrid/callback"],"post_logout_redirect_uris":["https://game.example/signed-out"]}'

Read the successful JSON envelope as {success:true,data:...}. A list contains data.applications. Create and rotate return data.client_id and data.client_secret; treat the entire response as sensitive and do not log it. Save a create response before retrying: writes are not idempotent. After a timeout, list apps before retrying creation or rotation.

Errors use {success:false,message:...}: 400 invalid metadata/action, 401 invalid/expired/revoked developer credential, 403 insufficient permissions, 404 app not owned or not found, 409 disabled app or registration limit, 413 oversized body, 415 wrong content type, 429 owner rate limit, 503 service unavailable. Use bounded backoff for 429/503 and do not automatically retry mutations after ambiguous responses. There is no unauthenticated or automatic email-based ownership registration.

OIDC endpoints and supported claims

Discover metadata at OpenID configuration. Pin the issuer exactly to https://auth.hybrid-id.com, without a trailing slash. Use a maintained OIDC library for discovery, signature verification and callback validation.

• Register with client_secret_basic token authentication, grant_type authorization_code, response_type code, PKCE S256. The portal sets these automatically.
• Request openid profile email, or fewer scopes when possible. Never request hybrid:session: it is reserved for first-party session bridging.
• Do not assume picture, phone, email_verified, KYC status, roles, agent permissions or decentralized credentials are included. Login does not grant profile write permissions.
• The opaque access token is for UserInfo, not Hybrid-Chain V2 access or authorization to your game API. Require the UserInfo sub to match the validated ID token.
• No refresh tokens/offline_access, implicit flow, public/native-client registration or device authorization flow is supported in this milestone. A game with a native client needs a backend and system-browser integration designed around its own session delivery.

Implement the browser and backend flow

• On your backend login route, generate random state, nonce and PKCE verifier. Store them server-side in a five-minute, single-use transaction bound to an opaque Secure, HttpOnly browser cookie. A state value alone must not let another browser claim the transaction.
• Redirect to the discovered authorization endpoint with the registered client ID, callback, scopes, state, nonce and S256 code challenge. Users enter passwords/MFA only on auth.hybrid-id.com.
• For the example helper, use response_mode=query and a top-level GET callback. SameSite=Lax transaction cookies work with this return navigation. A form_post callback needs a POST handler and deliberate cross-site cookie handling; do not blindly reuse Lax cookies.
• At the callback, atomically consume the browser-bound transaction. Validate state, nonce, signature, issuer, audience, expiration and PKCE through the OIDC library; exchange the code on the backend using the client secret.
• Fetch UserInfo server-side. Look up or create the local user by a unique (issuer, subject) key, never email. Rotate your app session ID, clear the transaction cookie and immediately redirect to a clean, validated local destination.
• Use Cache-Control: no-store and Referrer-Policy: no-referrer on callbacks. Redact callback query strings, Authorization headers, tokens and secrets from proxy logs, application logs and telemetry. Do not load analytics or third-party scripts on callbacks.

Node.js protocol helper

Use Node.js 22+ and openid-client. Download the server-only helper. This helper handles the protocol; your app must supply the database, browser-bound transaction store, CSRF protection and secure local sessions. It is not a complete login server.

npm install [email protected]

import { createClient, beginSignIn, finishSignIn } from "./hybrid-id-node.mjs";

const config = await createClient({
  clientId: process.env.HYBRID_CLIENT_ID,
  clientSecret: process.env.HYBRID_CLIENT_SECRET,
});

// GET /auth/hybrid/start (server-side):
const { url, transaction } = await beginSignIn(config, process.env.HYBRID_CALLBACK_URL);
// Save transaction in your server store, bound to this browser, then redirect to url.

// GET /auth/hybrid/callback (server-side):
// Atomically take the transaction using the browser cookie + returned state.
// Construct callback URL from the fixed configured URL and incoming query, NOT Host.
const user = await finishSignIn(config, callbackUrl, storedTransaction);
// Upsert local user by UNIQUE(user.issuer, user.subject).
// Issue your own rotated secure HttpOnly session cookie.
// user.idToken is server-only, for optional shared logout. Never serialize user wholesale.

Profile ownership and account linking

The pairwise subject is stable within the callback-hostname sector, not a universal cross-app user ID. Two registrations with the same sector can share a subject. Never use email as the primary key or silently merge accounts by email. To link an existing game account, require a current authenticated game session and a successful Hybrid-ID login, verify neither identity is already linked to another account, and commit the unique binding atomically.

Hybrid-ID does not yet provide generic per-app key/value storage. Do not invent an endpoint for it or store game state in identity profile fields. Future developer plans may add bounded storage; neither the proposed 100-user free tier nor 1 KB per-user allowance is an active product entitlement.

Sessions and logout

• Your app owns its session lifetime, authorization, device list and revocation. Hybrid-ID browser SSO, provider grants and app sessions are separate.
• Current provider defaults: authorization code 60 seconds, access token 300 seconds, provider session up to eight hours. Establish your own reasonable session policy and reauthenticate as needed.
• Local logout should be a CSRF-protected POST that destroys your app session. Optional shared sign-out uses the discovered end_session_endpoint, the stored ID token, an exact registered post_logout_redirect_uri and fresh, validated logout state. The helper exports sharedLogoutUrl for this.
• Ending shared sign-in or disabling a registration does not magically terminate every downstream app session. Backchannel/global downstream logout is not implemented.

Usage, limits and developer billing

Developer applications shows the number of unique identities issued an app access token and token issuances in the current UTC month. These counters begin with registration and do not represent all API calls, active game players or total accounts in your game database. The list API returns these values in each app’s usage object.

Developer billing is separate from any Hybrid-Chain subscription. Paid tiers, credit-card/crypto checkout, overage charging, storage quotas and generalized API-call billing are not enabled. The dashboard reports profile_storage: not_available and billing: not_enabled rather than fictitious usage or allowances.

Acceptance checks before launch

• A new consenting user signs in, returns to the exact game callback and receives a local app session. A returning user resolves to the same local account by (iss, sub).
• Cancelling consent, expired state, a different browser, replayed callbacks, wrong nonce, wrong PKCE, invalid signature/audience/issuer and unregistered callbacks fail without creating a session.
• Existing game-account linking requires proof of control of both accounts; email changes never create or merge game accounts.
• Agent credentials cannot list or mutate another owner’s apps. A read-only credential cannot create apps or rotate secrets. Revoked or expired credentials fail.
• Secret rotation rejects the old secret; disabling stops new authorizations. Local logout clears the game session and shared logout returns only to a registered URL.
• Logs contain no passwords, raw authorization codes, bearer credentials, client secrets, ID tokens or profile data. Store all credentials outside your repository and client bundle.
• Test with an actual existing Hybrid-ID account before launch. Automated fixtures establish protocol behavior; they do not prove your game deployment and browser session handling.

Prompt to give your integration agent

Integrate Hybrid-ID using https://hybrid-id.com/developers/integration.
Register/manage the app with an owner-delegated developer API credential, or use an existing portal registration.
Use confidential backend OIDC Authorization Code + PKCE S256; issuer https://auth.hybrid-id.com.
Do not expose secrets to the game client. Do not implement Hybrid password collection.
Keep game profiles/progress in our database, keyed by validated (issuer, subject).
Link shared identity edits to Hybrid-ID. Do not invent profile-storage or billing APIs.
Implement browser-bound state/nonce transactions, secure app sessions and the guide’s failure-case tests.
Request credentials through the environment/secret store; do not print them.
Read the machine version at https://hybrid-id.com/integrations/hybrid-id-guide.md.

Related references: Hybrid-ID developer portal, identity V2 reference, developer management OpenAPI, contact. The V2 reference describes separate identity APIs; an OIDC game access token does not automatically authorize them.