Create a Hybrid-ID

DEVELOPER GUIDE

A small profile.
A clear boundary.

Store lightweight preferences and application context in Hybrid-ID. Each application and user gets an isolated data bucket. This API does not edit canonical identity facts or grant access to another app’s data.

Manage Developer Apps

Connect in four steps

  1. Enable app-data storage when creating or editing your registered app.
  2. Request openid profile app:data through your existing Authorization Code + PKCE flow. The user sees a separate storage permission.
  3. From your backend, call https://hybrid-id.com/api/developer/v1/profile-data with HTTP Basic authentication using your app client ID and secret, plus X-Hybrid-User-Token containing the user’s Hybrid-ID access token.
  4. Use GET to read. Use POST to replace or delete. The service derives the app and user from authenticated credentials; no user ID is accepted from your request.

Developer automation credentials cannot use this data API. Keep the client secret and access token on your backend. Access requires an unexpired token, live grant, current Identity session and enabled app-data permission. Access tokens currently last five minutes; restart the authorization flow when needed.

Read and update safely

GET returns version, entries and encoded bytes. An unused bucket starts at version zero. Replace requires the version you just read; a conflict returns 409 so you can reload instead of overwriting another update.

{
  "action": "replace",
  "expected_version": 0,
  "entries": {
    "theme": {
      "value": "dark",
      "editable": true
    },
    "membershipLabel": {
      "value": "Standard",
      "editable": false
    }
  }
}

Delete with {"action":"delete","expected_version":1}. Use the actual returned version.

Limits and permissions

  • Developer: 25 keys, 256 UTF-8 bytes per value, 8 KiB total encoded profile and 100 stored app/user profiles and 1 MiB pooled storage across the developer account.
  • Keys are 1–64 ASCII characters, starting with a letter. Letters, digits, dots, underscores and hyphens are accepted; reserved prototype keys are rejected.
  • Values are strings. Every entry declares editable: true for a user preference or false for application-controlled data.
  • Users can inspect, export and delete the whole bucket. Do not treat its existence as a payment receipt or a verified credential.
  • Requests are limited to 120 per minute per app/user. Overages are not charged automatically.
Compare storage plans ↗

Response handling

401: credential, consent or session expired. 403: app access disabled or permission denied. 409: quota exceeded or version conflict. 429: retry after the rate-limit window. Do not blindly retry a conflicting write. Pooled storage is checked transactionally across all apps, including user edits. The billing API reports catalog version, usage and warnings. Monthly identity admission is capped before access-token issuance; an over-quota token exchange returns OAuth access_denied. Already-counted identities can return within the UTC month. No automatic overage billing is active. Reads and deletion remain available after a plan downgrade; writes must fit the current allowance.

App data is encrypted at rest and is not published to the Explorer. Profile images, documents, passwords, verification results and large agent memories remain in their dedicated services. The account owner’s developer plan is distinct from the user’s personal identity and any Hybrid-Chain subscription.