Exchange Code

Exchange access code

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

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.komerza.com/oauth2/{appId}/exchange/{code}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.komerza.com/oauth2/{appId}/exchange/{code}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.komerza.com/oauth2/{appId}/exchange/{code}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.komerza.com/oauth2/{appId}/exchange/{code}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "<string>",
  "code": "<string>",
  "data": "<string>"
}

{
  "success": true,
  "message": "<string>",
  "code": "<string>",
  "data": "<unknown>"
}

{
  "success": true,
  "message": "<string>",
  "code": "<string>",
  "data": "<unknown>"
}

{
  "success": true,
  "message": "<string>",
  "code": "<string>",
  "data": "<unknown>"
}

GET

oauth2

{appId}

exchange

{code}

Exchange access code

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

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.komerza.com/oauth2/{appId}/exchange/{code}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.komerza.com/oauth2/{appId}/exchange/{code}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.komerza.com/oauth2/{appId}/exchange/{code}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.komerza.com/oauth2/{appId}/exchange/{code}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "<string>",
  "code": "<string>",
  "data": "<string>"
}

{
  "success": true,
  "message": "<string>",
  "code": "<string>",
  "data": "<unknown>"
}

{
  "success": true,
  "message": "<string>",
  "code": "<string>",
  "data": "<unknown>"
}

{
  "success": true,
  "message": "<string>",
  "code": "<string>",
  "data": "<unknown>"
}

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

Last modified on July 31, 2026

API Documentation

Reference

OAuth2

User

Stores

Products

Categories

Variants

Coupons

Tickets

Customers

Orders

Reviews

Affiliates

Webhooks

Overview

Path Parameters

Headers

Response

Using the API Key

Token Properties

Error Responses

Complete Flow Example

Authorizations

Path Parameters

Response

​Overview

​Path Parameters

​Headers

​Response

​Using the API Key

​Token Properties

​Error Responses

​Complete Flow Example

Authorizations

Path Parameters

Response

Overview

Path Parameters

Headers

Response

Using the API Key

Token Properties

Error Responses

Complete Flow Example