Upstream authentication

Secure your backend so that only Kobaru-proxied traffic is accepted. The proxy can inject an API key into every request it forwards to your upstream API.

Why use upstream authentication

Without upstream auth, anyone who knows your backend URL can bypass the proxy and access your API directly. With it:

Only requests coming through Kobaru's payment gateway reach your backend

You can use your existing authentication middleware to validate the injected key

Direct access attempts fail because they don't have the key

How it works

You configure an API key and header format in the Console

The key is encrypted before storage

On each proxied request, the gateway decrypts the key and injects it as the configured header

Your backend validates the key using your existing auth middleware

Configuration

Located in the service create/edit dialogs under Upstream Authentication.

Settings

Field	Options	Description
Upstream Authentication	None / API Key	Whether to inject authentication
Header Format	`Authorization: Bearer` / `X-API-Key` / `api-key`	How the key is sent to your backend
API Key	Your secret	The key to inject (encrypted before storage)

Header formats

Preset	Header sent to your backend
`Authorization: Bearer`	`Authorization: Bearer <your-key>`
`X-API-Key`	`X-API-Key: <your-key>`
`api-key`	`api-key: <your-key>`

Header injection order

The gateway processes headers in this order:

The Authorization header is removed (prevents credential leakage to upstream)

The Payment-Signature header is removed

Your upstream API key is injected via the configured header

If the preset is Authorization: Bearer, the header is first cleared of the payment token, then set to your merchant key.

Testing your configuration

The Console provides two testing methods to verify your upstream authentication works.

Health check (before saving)

Tests a new or changed key before the service is saved. Available in both create and edit dialogs.

The Console auto-derives a health check URL from your base URL (defaults to /health)

You can edit the full URL

Click Check to test the connection

Shows the HTTP status and latency

This catches configuration errors before they affect live traffic.

Test connection (after saving)

Tests the stored encrypted key for an existing service. Only available in the edit dialog when a key is already configured.

Click Test Connection

Choose a path to test (e.g., /health, /ping, /status)

The Console decrypts the stored key and makes a real request to your backend

Shows success/failure and HTTP status

Use this to verify the stored key still works, for example after rotating keys on your backend.

Comparison

Feature	Health check	Test connection
When available	Create and edit	Edit only (key must exist)
What it tests	New/changed key	Stored encrypted key
Service ID needed	No	Yes
URL control	Full URL editable	Path only
Shows latency	Yes	No
Auth header injected	No	Yes (per config)

Security

Keys are encrypted before database storage

Keys are never returned via the API (only hasProxyAuthKey: true/false)

Your keys are stored securely and decrypted only when needed for request forwarding

Next steps

With your service and upstream auth configured, set up capabilities and routes to define pricing and payment methods.

Upstream authentication

Why use upstream authentication#

How it works#

Configuration#

Settings#

Header formats#

Header injection order#

Testing your configuration#

Health check (before saving)#

Test connection (after saving)#

Comparison#

Security#

Next steps#