> ## Documentation Index
> Fetch the complete documentation index at: https://docs.komerza.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth2 Integration

> Allow third-party applications to access user accounts with their consent

## Overview

Komerza's OAuth2 system enables third-party developers to create applications that can securely access user accounts with explicit user consent. This allows you to build integrations, plugins, and services that interact with Komerza stores on behalf of users.

<Card title="Create Your Application" icon="rocket" href="https://dashboard.komerza.com/developers/applications">
  Register your OAuth2 application in the Komerza Dashboard
</Card>

## How It Works

<Steps>
  <Step title="Create an Application">
    Register your application with Komerza, specifying the permissions you need
    and your redirect URLs.
  </Step>

  <Step title="User Authorization">
    Redirect users to Komerza's authorization page where they can review and
    approve your app's access.
  </Step>

  <Step title="Receive Authorization Code">
    After approval, users are redirected back to your app with a temporary
    authorization code.
  </Step>

  <Step title="Exchange for API Key">
    Exchange the authorization code for a JWT API key that grants access to the
    authorized stores.
  </Step>
</Steps>

## Authorization URL

Send users to the following URL to initiate the OAuth2 flow:

```
https://dashboard.komerza.com/auth/authorize
```

### Query Parameters

| Parameter      | Required | Description                                            |
| -------------- | -------- | ------------------------------------------------------ |
| `client_id`    | Yes      | Your application's Client ID                           |
| `redirect_uri` | Yes      | One of your registered redirect URLs                   |
| `state`        | No       | Optional value passed back to your app in the callback |

### Example Authorization URL

```
https://dashboard.komerza.com/auth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https://myapp.com/callback&state=random123
```

## OAuth2 Flow Diagram

```
┌─────────────┐                              ┌─────────────┐
│   Your App  │                              │   Komerza   │
└──────┬──────┘                              └──────┬──────┘
       │                                            │
       │  1. Redirect user to authorization URL     │
       │ ─────────────────────────────────────────> │
       │                                            │
       │           2. User reviews & approves       │
       │                                            │
       │  3. Redirect back with authorization code  │
       │ <───────────────────────────────────────── │
       │                                            │
       │  4. Exchange code for API key              │
       │ ─────────────────────────────────────────> │
       │                                            │
       │  5. Return JWT API key                     │
       │ <───────────────────────────────────────── │
       │                                            │
       │  6. Make API calls with Bearer token       │
       │ ─────────────────────────────────────────> │
       │                                            │
```

## Permissions & Scopes

When creating your application, you must specify which permissions (scopes) your app requires. Users will see these permissions during the authorization flow and can choose which stores to grant access to.

<Card title="View All API Scopes" icon="shield-check" href="/api-reference/scopes">
  Complete reference for all available permission scopes
</Card>

## Security Best Practices

<Warning>
  **Client Secret Security**: Your client secret is like a password. Never
  expose it in client-side code, public repositories, or logs.
</Warning>

<CardGroup cols={2}>
  <Card title="Use HTTPS" icon="lock">
    All redirect URLs should use HTTPS in production environments.
  </Card>

  <Card title="Server-Side Exchange" icon="server">
    Always exchange authorization codes from your backend server, never from
    client-side code.
  </Card>

  <Card title="Secure Storage" icon="vault">
    Store client secrets and API keys securely using environment variables or
    secret management systems.
  </Card>

  <Card title="Minimal Permissions" icon="user-shield">
    Only request the permissions your application actually needs.
  </Card>
</CardGroup>

## Token Characteristics

| Property                        | Value                 |
| ------------------------------- | --------------------- |
| **Token Type**                  | JWT (JSON Web Token)  |
| **Authorization Code Validity** | 1 minute (single-use) |
| **API Key Validity**            | Until revoked         |
| **Max Redirect URLs**           | 10 per application    |

## Quick Links

<Card title="Exchange Code" icon="arrow-right-arrow-left" href="/api-reference/oauth2/exchange">
  Exchange authorization code for API key
</Card>