Base URLs
XID is an identity provider. The instance domain is the OIDC issuer, API base URL, Hosted Auth base URL, and console base URL. Organizations provide policy, branding, membership, and resource isolation.
Start by reading /.well-known/openid-configuration from the instance domain. The discovery document gives your app the authorization, token, userinfo, logout, and JWKS endpoints for that issuer.
| Surface | Path | Use |
|---|---|---|
| OIDC discovery | /.well-known/openid-configuration |
Read issuer metadata before configuring a relying party. |
| Authorization | /authorize |
Redirect users to the unified Hosted Auth flow. |
| Token | /token |
Exchange an authorization code or refresh token. |
| Userinfo | /userinfo |
Read claims for a valid access token. |
| Management API | /v1/* |
Manage organization resources from your backend. |
Minimum integration
- Create an OIDC application and register exact redirect URI values.
- Use authorization code flow with PKCE S256 for browser and native clients.
- Validate ID tokens and access tokens against the issuer and JWKS URI.
- Store refresh tokens server side or in a secure native credential store.
Authorization request
sequenceDiagram participant Browser participant RP participant XID RP->>Browser: /authorize + PKCE S256 Browser->>XID: /authorize + PKCE S256 XID->>Browser: /sign-in Browser->>XID: WebAuthn / SSO XID->>Browser: code Browser->>RP: code RP->>XID: /token + PKCE S256 XID->>RP: ID token + access token
const authorizeUrl = new URL('https://xid.dev/authorize')
authorizeUrl.searchParams.set('client_id', clientId)
authorizeUrl.searchParams.set('redirect_uri', redirectUri)
authorizeUrl.searchParams.set('response_type', 'code')
authorizeUrl.searchParams.set('scope', 'openid profile email')
authorizeUrl.searchParams.set('code_challenge', codeChallenge)
authorizeUrl.searchParams.set('code_challenge_method', 'S256')