Exchange Code

Exchanges an authorization code for an API key.

GET /oauth2/{appId}/exchange/{code}

Exchange access code

cURL

curl --request GET \
  --url https://api.komerza.com/oauth2/{appId}/exchange/{code} \
  --header 'Authorization: Bearer <token>'

200

{
  "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

Parameter	Type	Description
appId	string	Your application’s Client ID
code	string	The authorization code received from the callback

Headers

Header	Required	Description
X-Client-Secret	Yes	Your application’s 72-character client secret
User-Agent	Yes	Your 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

Error	Description
invalid_code	The authorization code is invalid or has already been used
code_expired	The authorization code has expired (codes are valid for 1 minute)
invalid_client_secret	The client secret is incorrect
app_not_found	The 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

200

text/plain

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.