Getting started

Start on XID Cloud

XID Cloud runs at https://xid.dev and is free. You need an organization, an application and a few lines of code.

Choose Start free at the top of this page. Sign up and name your organization; XID creates it and opens the Console.
In the Console, open Applications and create an application. Register the exact redirect URI of your app and copy its client ID.
Wrap your app in XidProvider with the issuer https://xid.dev and your client ID, then verify access tokens on your backend with authenticateRequest.

import { XidProvider } from '@xid-kit/react'

export function App() {
  return (
    <XidProvider
      mode="oidc"
      issuer="https://xid.dev"
      clientId="client_abc123"
      redirectUri="https://app.example.com/auth/callback"
    >
      <Layout />
    </XidProvider>
  )
}

import { authenticateRequest } from '@xid-kit/backend'

const state = await authenticateRequest(request, {
  jwtKey: env.XID_JWKS_PUBLIC_KEY,
  issuer: 'https://xid.dev',
})
if (!state.isSignedIn) return new Response('Unauthorized', { status: 401 })

The SDKs are distributed as source in the XID repository. Any standard OIDC library also works with the endpoints below.

On a self-hosted instance, use your own instance domain instead of https://xid.dev. Self-hosting covers the deployment.

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')