---
title: "Getting started"
description: "Sign up on XID Cloud, create an app and verify its tokens."
locale: "en"
---

> Documentation Index
> Fetch the relevant documentation index at: https://xid.fngx.org/en/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`.

```tsx
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>
  )
}
```

```ts
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](/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

```mermaid
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
```

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

Source: https://xid.fngx.org/getting-started/index.mdx