zitadel/apps/docs/content/guides/start/quickstart.mdx

---
title: The ZITADEL Quick Start Guide
description: Learn how to integrate OIDC PKCE authentication in React using ZITADEL in under 5 minutes.
sidebar_label: Quick Start Guide
keywords: [ZITADEL, React, OIDC, PKCE, Authentication, Identity Management]
framework: React
stack: Node.js
---

import { ResponsivePlayer } from "@/components/player";

This sample app implements the [OIDC PKCE](/guides/integrate/login/oidc/login-users) flow for secure authentication.
- Login: Exchanges a code challenge for an access token via ZITADEL.
- Authorize: Uses the token to retrieve profile data from the userinfo endpoint.
- Logout: Clears the local session and revokes the token.
## Get Started with ZITADEL Cloud

Set up your ZITADEL account and organization to begin managing identities for your applications.
### 1. Create your Account and Organization

You first need access to the ZITADEL Cloud Customer Portal.
This is the administrative hub for managing your billing, teams, and instances.
1. **Sign Up**: Go to [zitadel.com](http://zitadel.com) and select Sign Up.
2. **Onboarding**: Follow the prompts to verify your email and set up your Portal Team.
  - Tip: We recommend using Passkeys for a secure, passwordless login experience.
3. **Access**: Once authenticated, you will be redirected to the Customer Portal dashboard.

![Home Page](../../../public/img/guides/quickstart/cloud_sign_up.png)
![Registration Page](../../../public/img/guides/quickstart/cloud_register.png)

### 2. Quick Onboarding

Complete the brief onboarding questions.
This data helps us prioritize the development of new features, SDKs, and integrations that matter most to our community.
![](../../../public/img/guides/quickstart/onboarding_questions.png)

### 3. Create your ZITADEL instance

An [Instance](/concepts/structure/instance) is a fully isolated identity environment with its own users, policies, and data.
Most developers use separate instances to isolate Development, Test, and Production workflows.

Follow these steps to deploy your first instance:
1. **Start**: Click Create Instance on your dashboard.
2. **Identity**: Provide an Instance Name (e.g., dev-environment). This will be used to generate your default domain (e.g., dev-environment-xxxx.zitadel.cloud).
3. **Locality**: Select your Region.
  - Note: Choosing a region close to your users minimizes latency and helps with data residency compliance.
4. **Admin Setup**: Create your Instance Administrator. This user has "root" permissions to manage all organizations, policies, and settings within this specific instance.
5. **Deploy**: Review your configuration and click Create Instance.

![Create Instance](../../../public/img/guides/quickstart/cloud_create_instance.png)
### 4. Create your Project and Application

In ZITADEL, [**Applications**](/guides/manage/console/applications-overview) are grouped into [**Projects**](/guides/manage/console/projects-overview).
This allows multiple apps (like a React frontend and a Go backend) to share the same roles and authorizations.
#### Launch the Management Console

Click **Create your app**. This opens the Management Console for your instance in a new tab.
Log in using the Admin credentials you just created.
![Create App](../../../public/img/guides/quickstart/cloud_create_app.png)

#### Step 1: Define your Project
- **Name**: Enter a name (e.g., Project1).
- **Framework**: Select React (or choose Other if your stack isn't listed).
- **Continue**: Click the Continue button.
![](../../../public/img/guides/quickstart/create_project_react.png)

#### Step 2: Review Default Configuration
ZITADEL automatically configures the best security settings for your selected framework.
- **Auth Strategy**: [Authorization Code Flow](/apis/openidoauth/grant-types#authorization-code) with [PKCE](/apis/openidoauth/grant-types#authorization-code). This modern standard ensures tokens are exchanged securely without needing a client secret in your frontend.
- **Redirect URIs**: These define where users return after authentication:
  - Redirect URI: http://localhost:3000/callback (Landing page after login)
  - Post Logout URI: http://localhost:3000/ (Landing page after logout)

![](../../../public/img/guides/quickstart/project_config_overview_react.png)

### 5. Collect your Integration Keys
To connect your React application to ZITADEL, you need two primary configuration values.
These are typically stored as environment variables in your project.

1. **Client ID** Navigate to Configurations in the left sidebar. This is the unique public identifier for your React application.
![Get Client ID](../../../public/img/guides/quickstart/project_client_id.png)
2. **Issuer URL** Click on URLs in the left sidebar to find your **Discovery Endpoint**.
- The Value: Copy the issuer URL (e.g., https://your-instance.zitadel.cloud).
- Why it matters: ZITADEL supports OIDC Discovery. By providing just the Issuer URL to your SDK, the library automatically finds the login, logout, and token endpoints for you.
![Get URLs](../../../public/img/guides/quickstart/project_urls.png)

## Integrate ZITADEL into your React App
### How the Authentication Flow Works
ZITADEL handles the complexity of the OIDC handshake so your app stays secure without manual token management.
1. **Login**: App redirects the user to ZITADEL with a PKCE challenge.
2. **Auth**: User authenticates on the ZITADEL hosted login page.
3. **Exchange**: ZITADEL returns an Auth Code, which the app exchanges for an Access Token.
4. **Tokens**: The app shows the Access and ID Token
5. **Logout**: The app clears local tokens and terminates the ZITADEL session.

### 1. Prerequisites
- [Node.js](https://nodejs.org/): v16 or later.
- Code Editor: [VS Code](https://code.visualstudio.com/) or similar
- [Yarn](https://yarnpkg.com/): This project uses Yarn for dependency management.

### 2. Get the Example Project

Clone the repository and move into the project directory:
```bash
git clone https://github.com/zitadel/zitadel-react.git
cd zitadel-react```

### 3. Build and Install

Since this repo contains the SDK source, you need to build the library before running the example:
```bash
# Build the SDK library
cd lib && yarn install && yarn build

# Install example app dependencies
cd .. && yarn install```

### 4. Configure your Credentials

Open src/App.tsx and update the config object with the **Issuer** and **Client ID** you collected in Step 5.

```typescript
const config: ZitadelConfig = {
    authority: "https://your-instance.zitadel.cloud", // Your Issuer URL
    client_id: "YOUR_CLIENT_ID",                      // Your Client ID
    redirect_uri: "http://localhost:3000/callback",
    post_logout_redirect_uri: "http://localhost:3000",
    response_type: 'code',
    scope: 'openid profile email'
};
```

### 5. Run the Application

Start your development server:
```bash
yarn start
```

Your app will be live at `http://localhost:3000`. Click Login to test the full PKCE flow!

![React Example App](../../../public/img/guides/quickstart/react_example_app.png)

## Success! 🚀
You’ve successfully integrated ZITADEL into a React application.

### What’s next?
- [**SSO**](/guides/integrate/services): Learn how to add SSO to your services
- [**Customize the UI**](/guides/manage/customize/branding): Make the login page your own with Branding.
- [**Explore the API**](/apis/introduction): Check out the ZITADEL API Reference for advanced integrations.

Need help? Join our [Discord community](https://zitadel.com/chat) or explore the full Documentation. Happy coding!