DEVELOPER INTEGRATION · VERSION 1.0.0
← Integration guideAPI reference
Version 1.0.0 describes the deployed identity service and the shared program-side integration. Example domains and angle-bracket values are placeholders.
Identity service endpoints
Base URL: https://identity.city.digikraft-technologies.com. Token and introspection requests are form encoded; enrollment requests are JSON.
| Method & path | Purpose / authentication |
|---|---|
GET /.well-known/openid-configuration | Live discovery; public. |
GET /o/.well-known/jwks.json | RSA public signing keys; public. |
GET /o/authorize/ | Browser authorization; verified citizen session, state, nonce and S256 PKCE. |
POST /o/token/ | Code exchange or rotating refresh; confidential backend client authentication. |
GET /o/userinfo/ | Scope-filtered claims; central bearer access token. |
POST /o/revoke/ | OAuth token revocation; confidential client authentication. |
POST /api/integrations/introspect/ | Bound session status; HTTP Basic client authentication; only tokens belonging to that client are active. |
POST /api/v1/accounts/register/POST /api/v1/accounts/recover/ | Public enrollment and recovery; no client secret. |
GET /api/health/ | Database connectivity; public. |
Program-side endpoints
These endpoints run on each program's backend, not on the SSO host. Mount them under /api/v1/sso/.
| Endpoint | Request / result |
|---|---|
GET config/ | Public; enabled, account_url, registration_url, recovery_url. |
POST begin/ | return_uri, code_challenge, optional link; returns authorization_url. Bearer authentication is required when linking. |
GET callback/ | Provider redirect; consumes pending state, validates identity and redirects with a one-use sso_code or sso_error. |
POST exchange/ | code, code_verifier; returns local access/refresh. |
GET status/ | Local bearer authentication; linked and account_url. |
POST logout/ | Local bearer authentication; HTTP 204, revokes the current program-side session. |
Identity claims
ID tokens include iss, sub, aud, exp, iat, nonce, sid and security_version, plus name/email claims for the requested scopes. Require email_verified: true. Use issuer/subject as the durable key. Do not derive operational privileges from email, name or any identity claim.
Active introspection additionally supplies client_id, scope, exp, phone_number and phone_number_verified: false. An inactive token returns only active: false. A supplied phone is unverified; do not use it as proof of ownership.
Supported integration profile
New connections use authorization code, S256 PKCE, RS256 ID tokens and a confidential backend. Use HTTP Basic for backend credentials. Password grants, implicit sign-in, dynamic public registration and RP-initiated logout are unavailable. Never treat an ID token as a program API access token.
The contracts have separate server URLs so importing them cannot accidentally send program requests to the identity host. Replace the program spec's illustrative server with your own HTTPS API origin. Complete the acceptance checklist before production onboarding.