Skip to main content

​
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.

Create Your Application

Register your OAuth2 application in the Komerza Dashboard

​
How It Works

1

Create an Application

Register your application with Komerza, specifying the permissions you need and your redirect URLs.
2

User Authorization

Redirect users to Komerza’s authorization page where they can review and approve your app’s access.
3

Receive Authorization Code

After approval, users are redirected back to your app with a temporary authorization code.
4

Exchange for API Key

Exchange the authorization code for a JWT API key that grants access to the authorized stores.

​
Authorization URL

Send users to the following URL to initiate the OAuth2 flow: 
https://dashboard.komerza.com/auth/authorize

​
Query Parameters

ParameterRequiredDescription
client_idYesYour application’s Client ID
redirect_uriYesOne of your registered redirect URLs
stateNoOptional 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.

View All API Scopes

Complete reference for all available permission scopes

​
Security Best Practices

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

Use HTTPS

All redirect URLs should use HTTPS in production environments.

Server-Side Exchange

Always exchange authorization codes from your backend server, never from client-side code.

Secure Storage

Store client secrets and API keys securely using environment variables or secret management systems.

Minimal Permissions

Only request the permissions your application actually needs.

​
Token Characteristics

PropertyValue
Token TypeJWT (JSON Web Token)
Authorization Code Validity1 minute (single-use)
API Key ValidityUntil revoked
Max Redirect URLs10 per application

Exchange Code

Exchange authorization code for API key