---
title: "Getting started"
description: "Connect an application to XID with OIDC discovery and Hosted Auth."
locale: "en"
---

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

# Getting started

## 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.dev/getting-started/index.mdx