Skip to main content
GET
/
oauth2
/
{appId}
/
exchange
/
{code}
Exchange access code
curl --request GET \
  --url https://api.komerza.com/oauth2/{appId}/exchange/{code} \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "message": "<string>",
  "code": "<string>",
  "data": "<string>"
}

​
Overview

Exchange an authorization code for a JWT API key. This is the final step in the OAuth2 flow, converting the temporary code into a permanent access token.
This endpoint requires the X-Client-Secret header for authentication instead of the standard Authorization header.

​
Path Parameters

ParameterTypeDescription
appIdstringYour application’s Client ID
codestringThe authorization code received from the callback

​
Headers

HeaderRequiredDescription
X-Client-SecretYesYour application’s 72-character client secret
User-AgentYesYour application identifier
Server-Side Only: This request must be made from your backend server, never from client-side code. The client secret must remain confidential.

​
Response

{
  "success": true,
  "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
The data field contains a JWT API key that you can use to make authenticated API requests.

​
Using the API Key

Include the JWT as a Bearer token in subsequent API requests: 
curl -X GET https://api.komerza.com/stores/STORE_ID \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "User-Agent: MyApp/1.0"

​
Token Properties

The JWT API key:
  • Grants access only to the stores the user authorized
  • Has permissions limited to the scopes you requested and the user approved
  • Does not expire until the user revokes authorization
  • Is tied to the specific user and application

​
Error Responses

ErrorDescription
invalid_codeThe authorization code is invalid or has already been used
code_expiredThe authorization code has expired (codes are valid for 1 minute)
invalid_client_secretThe client secret is incorrect
app_not_foundThe application ID is invalid

​
Complete Flow Example

// 1. User clicks "Connect with Komerza" in your app
const authUrl = `https://dashboard.komerza.com/auth/authorize?client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}&state=${randomState}`;
window.location.href = authUrl;

// 2. User authorizes on Komerza, redirected back to your app
// URL: https://myapp.com/callback?code=ENCRYPTED_CODE&state=randomState

// 3. Your backend exchanges the code for an API key
const response = await fetch(
  `https://api.komerza.com/oauth2/${CLIENT_ID}/exchange/${code}`,
  {
    headers: {
      "x-client-secret": process.env.CLIENT_SECRET,
      "User-Agent": "MyApp/1.0",
    },
  }
);

const { data: apiKey } = await response.json();

// 4. Store the API key securely and use it for API calls
const stores = await fetch("https://api.komerza.com/stores", {
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "User-Agent": "MyApp/1.0",
  },
});

Authorizations

​
Authorization
string
header
required

Your API key goes here

Path Parameters

​
appId
string<uuid>
required

The application ID.

​
code
string
required

The authorization code to exchange.

Response

The object was successfully returned.

Represents a default generic response for API endpoints.

​
success
boolean
required

Indicates whether the operation or response was successful.

​
message
string | null

A descriptive message providing additional context or information about the response.

​
code
string | null

The error code (if there was an error) to use when referencing the error

​
data
string | null

Represents the data associated with a response.