API Keys

API keys are used for server-to-server authentication with the Kotani Pay API. There are two ways to generate them: from the dashboard (no code required) or via the API using the magic link authentication flow.

Method 1 — Generate from the Dashboard

The easiest way to get an API key is directly from the backoffice dashboard.

Log in to backoffice.kotanipay.com
Click API Keys in the left sidebar
Click Generate New Key and choose the key type (integrator-level or user-bound)
Copy the key immediately — it will not be shown again after you leave the page
To revoke a key, find it in the list and click Revoke

Method 2 — Generate via the API

If you need to generate keys programmatically, use the magic link authentication flow to get a JWT, then call the key generation endpoint.

Step 1 — Get a JWT via Magic Link

Request a magic link

Call POST /auth/login with your registered integrator email:

curl -X POST https://sandbox-api.kotanipay.com/api/v3/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourcompany.com"}'

Response:

{
  "success": true,
  "message": "login magic link sent to your email",
  "data": {}
}

Click the link in your email

Check your inbox for an email from Kotani Pay. Click the Login to Kotani Pay button (or copy the URL into your browser).

The magic link expires in 1 hour. If it has expired, repeat the POST /auth/login call to get a fresh one.

Receive your JWT

Clicking the link hits GET /api/v3/auth/verify?hash=... and returns your tokens:

{
  "success": true,
  "message": "ok",
  "data": {
    "user_id": "abc123",
    "session_id": "sess_xyz",
    "token_id": "tok_123",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Save the token — you’ll use it in the next step. The JWT expires after 1 hour; use GET /api/v3/auth/refresh-token with your refresh_token to get a new one without re-doing the magic link flow.

Human verification: If the link is opened by an email security scanner before you click it, you may be redirected to a verification page. Complete the prompt — the system re-validates the request and issues your tokens normally.

Step 2 — Generate the Key

Two endpoints are available depending on whether you need a signing secret: Key only:

curl -X GET https://sandbox-api.kotanipay.com/api/v3/auth/api-key \
  -H "Authorization: Bearer <your-jwt-token>"

Response:

{
  "success": true,
  "message": "Api-key generated successfully",
  "data": {
    "key": "eyJ1c2VyX2lkIjoiYWJjMTIzIiwiY3JlYXRlZF9hdCI6Ii4uLiJ9.a1b2c3d4e5f6..."
  }
}

Key + secret (for end-to-end payload verification):

curl -X GET https://sandbox-api.kotanipay.com/api/v3/auth/api-key/secure \
  -H "Authorization: Bearer <your-jwt-token>"

Response:

{
  "success": true,
  "message": "Api-key generated successfully",
  "data": {
    "key": "eyJ1c2VyX2lkIjoiYWJjMTIzIiwiY3JlYXRlZF9hdCI6Ii4uLiJ9.a1b2c3d4e5f6...",
    "secret": "7f3a9b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0"
  }
}

Store both values securely. The secret will not be shown again.

Using the API Key

Include the key in the Authorization header of every API request:

curl -X GET https://sandbox-api.kotanipay.com/health \
  -H "Authorization: Bearer eyJ1c2VyX2lkIjoiYWJjMTIzIi4uLn0=.a1b2c3d4..."

The API also accepts a JWT token in the same header — both formats are valid.

API Key Types

There are two ownership modes for an API key.

Integrator Level

Generated without a user assignment — gets wildcard (*) permissions, meaning full access to all operations. Use this for your main server-to-server integration.

User Bound

Generated tied to a specific dashboard user account. Starts with zero permissions — you assign only what that key needs via API Keys in the dashboard. Useful when you need scoped access (e.g., a key that can only initiate deposits but not withdrawals).

Testing

Getting Started

Essentials

Transaction Flows

Method 1 — Generate from the Dashboard

Method 2 — Generate via the API

Step 1 — Get a JWT via Magic Link

Step 2 — Generate the Key

Using the API Key

API Key Types

Integrator Level

User Bound

Next Steps

Webhooks

Balances & Settlement

​Method 1 — Generate from the Dashboard

​Method 2 — Generate via the API

​Step 1 — Get a JWT via Magic Link

​Step 2 — Generate the Key

​Using the API Key

​API Key Types

​Integrator Level

​User Bound

​Next Steps

Webhooks

Balances & Settlement

Method 1 — Generate from the Dashboard

Method 2 — Generate via the API

Step 1 — Get a JWT via Magic Link

Step 2 — Generate the Key

Using the API Key

API Key Types

Integrator Level

User Bound

Next Steps