---
title: "Authentication"
description: "Learn about KOMOJU's two API key types — secret and publishable — how to authenticate requests with HTTP Basic Auth, and how to manage API versioning."
url: "https://docs.priv.staging.komoju-dev.tools/en/docs/introduction/authentication"
source_url: "https://docs.priv.staging.komoju-dev.tools/en/docs/introduction/authentication.md"
language: en
last_modified: "2026-03-23"
---

KOMOJU offers merchants two types of API keys: secret and publishable. These keys are necessary for making API requests, and you can find them in the settings page of your merchant account. Each merchant account will have a pair of keys for both live and test environments.

API requests are authenticated through **[HTTP Basic Authentication](http://en.wikipedia.org/wiki/Basic_access_authentication)**. To authenticate, use your API key as the username and leave the password field empty. For example:

```shell
curl -u secret_key: "https://komoju.com/api/v1/payments"

```

# Secret Key

The secret key grants access to all API resources. It is crucial to store this key securely, as it has the potential to execute any action on your account. Make sure to keep your secret key on your server-side and never expose it to client-side applications.

# Publishable Key

Unlike secret keys, publishable keys can interact with a limited selection of API resources. It is safe to expose your publishable key publicly, as it cannot cause any damage.

The following actions can be performed using the publishable key:

- **[Create a token](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/tokens/POST/tokens)**
- **[Pay for a session](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/sessions/POST/sessions/%7Bid%7D/pay)**

# API Version

To ensure compatibility and maintain backward compatibility, KOMOJU API supports versioning through custom headers. You can specify the desired valid API version by including the `X-KOMOJU-API-VERSION` header in your requests, allowing integration with different versions of our service.

```shell
curl -H 'X-KOMOJU-API-VERSION: 2024-07-15' -u secret_key: "https://komoju.com/api/v1/payments"

```

You may also select and set an API version for your secret and publishable keys from the KOMOJU Dashboard. Go to the Merchant Settings menu and find the `Edit` button next to your key.

![KOMOJU Dashboard showing the API version selector next to the Edit button for secret and publishable keys](https://files.readme.io/a861c0e-Screenshot_2024-07-12_at_12.26.34.png)