Authentication

Ikawaari uses different credentials for different contexts. ik_XXX API keys are for server-to-server integrations. Interactive Ikawaari apps such as the merchant dashboard, ops console, and marketplace use OpenIddict access tokens.

Bearer Token

For a server integration, include your secret API key in the Authorization header:

curl https://api.ikawaari.com/api/v1/payment-intents \
  -H "Authorization: Bearer ik_test_sk_your_key_here" \
  -H "X-Environment: sandbox"

Environments

Credential prefix	Usage	Environment
ik_test_sk_	Server secret key	Sandbox
ik_live_sk_	Server secret key	Live
ik_test_pk_	Client publishable key	Sandbox
ik_live_pk_	Client publishable key	Live

Send X-Environment: sandbox or X-Environment: live with authenticated API calls. Never use a live key to simulate sandbox traffic.

Credential Model

Credential	Issuer	Usage
OpenIddict access token	Ikawaari Identity	First-party interactive sessions: dashboard, ops, marketplace
ik_test_sk_ / ik_live_sk_	Dashboard/API keys	Server-to-server API calls
ik_test_pk_ / ik_live_pk_	Dashboard/API keys	Client initialization only, never server APIs
Restricted keys	Dashboard/API keys	Server integrations with limited scopes
App tokens	Marketplace apps	Calls made by an installed app
Flow session tokens	UIFlow runtime	Short-lived hosted verification sessions
MerchantJwt	Legacy	Existing merchant dashboard compatibility

OpenIddict does not validate ik_XXX keys, and API key handlers do not validate OpenIddict tokens. Each credential is validated by its own handler, then Ikawaari resolves a canonical merchant context.

Marketplace Apps

The public marketplace catalog is available without authentication:

curl https://api.ikawaari.com/api/v1/public/marketplace/apps \
  -H "X-Environment: sandbox"

Merchant actions, such as installing an app, require an OpenIddict user session and a merchant context:

curl https://api.ikawaari.com/api/v1/merchant/marketplace/apps/{appId}/install-consent \
  -H "Authorization: Bearer OPENIDDICT_ACCESS_TOKEN" \
  -H "X-Environment: sandbox" \
  -H "X-Merchant-Account-Id: ma_xxxxx"

Marketplace consent and installation are restricted to merchant users with sufficient roles, such as owner or admin.

Server Calls With API Keys

Secret ik_XXX keys must only be used from your backend:

curl https://api.ikawaari.com/api/v1/payment-intents \
  -H "Authorization: Bearer ik_live_sk_your_key_here" \
  -H "X-Environment: live" \
  -H "Content-Type: application/json"

Never place an ik_live_sk_ or ik_test_sk_ key in browser code, mobile apps, or source control.

Security Best Practices

• Never expose API keys in client-side code, Git repositories, or logs
• Use environment variables to store API keys
• Restrict key scopes to the minimum required permissions
• Rotate keys regularly and revoke unused keys
• Use IP whitelisting for production keys when possible
• Never send access tokens in URLs; use the Authorization header
• Always send X-Environment to avoid sandbox/live ambiguity