Collection API Authentication

Authentication Model: API Key + OIDC

The Kulpay Collection API uses a dual authentication model combining API Key authentication with OIDC (OpenID Connect) identity providers. Unlike the core Kulpay API which uses license-based system authorization, the Collection API requires per-request authentication via Bearer tokens.

How It Works

The Collection API validates requests through two layers:

1. System License — The system-level license must be active (same as core Kulpay API)
2. Bearer Token — Each request must include a valid access token in the Authorization header

Request Format

All Collection API requests must include the Authorization header:

curl -X GET https://host:8080/v1/collection-requests \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json"

Token Acquisition

Access tokens are obtained from the configured OIDC identity provider. The system supports standard OAuth2 flows:

Flow	Use Case
Authorization Code	Web applications with server-side components
Client Credentials	Service-to-service communication (M2M)
Resource Owner Password	Trusted first-party applications

Example: Client Credentials Flow

curl -X POST https://idp.example.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret" \
  -d "scope=openid profile"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile"
}

Identity Providers

The Collection API supports configurable OIDC identity providers. Providers are managed through the Identity Provider Service. Compatible providers include:

Provider	Type	Description
Keycloak	OIDC	Enterprise identity and access management

Token Validation

The API validates tokens by:

1. Verifying the JWT signature against the provider's JWKS endpoint
2. Checking token expiration (exp claim)
3. Validating the issuer (iss claim) matches the configured provider
4. Confirming the audience (aud claim) includes the API
5. Extracting user identity and permissions from token claims

Account Context

Once authenticated, requests are scoped to the account associated with the authenticated identity. The account determines:

• Which collection methods are available
• Which collection requests are visible
• Which payments can be managed
• Onboarding status and capabilities

Comparison with Core API Authentication

Aspect	Core Kulpay API	Collection API
Auth Type	License-based (system-level)	API Key + OIDC (per-request)
Header Required	None	Authorization: Bearer <token>
Identity	System-level	Per-user / per-account
Token Source	Internal license key	External OIDC provider
Multi-tenancy	Single tenant	Multi-tenant (account-scoped)

Both APIs share the License Interceptor — the system license must be active regardless of the per-request authentication model.

Error Responses

401 Unauthorized

Returned when the Bearer token is missing, invalid, or expired.

{
  "code": "unauthorized",
  "message": "Invalid or expired access token",
  "request_id": "req_abc123"
}

403 Forbidden

Returned when the token is valid but the identity lacks permission for the requested operation.

{
  "code": "forbidden",
  "message": "Insufficient permissions for this operation",
  "request_id": "req_def456"
}

Token Refresh

When a token expires, clients should use the refresh token (if available) to obtain a new access token without re-authenticating:

curl -X POST https://idp.example.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=your_refresh_token" \
  -d "client_id=your_client_id"