Authentication

Kashimi uses the OAuth 2.0 Client Credentials flow to authenticate API requests. Every endpoint requires a valid Bearer token in the Authorization header. Follow the three steps below to obtain and use a token.

Encode your credentials

Combine your clientId and clientSecret with a colon, then Base64-encode the result:

base64("your-client-id:your-client-secret")

echo -n "your-client-id:your-client-secret" | base64

Request a token

Send a POST request to /api/v1/auth/token with your encoded credentials.Headers

Header	Value
`Authorization`	`Basic <base64-encoded-credentials>`
`Content-Type`	`application/x-www-form-urlencoded`

Body (form-encoded)

Field	Value
`grant_type`	`client_credentials`
`scope`	Space-separated list of scopes (see Available Scopes)

curl --request POST "https://api.kashimi.tech/api/v1/auth/token" \
  --header "Authorization: Basic BASE64_CLIENT_CREDENTIALS" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "scope=payments:read payments:write providers:read"

A successful response returns a JSON object:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 1800
}

Use the token

Pass the access_token in the Authorization header of every subsequent API request:

Authorization: Bearer <access_token>

Available Scopes

Scope	Description
`payments:read`	Read access to payments and payment statuses
`payments:write`	Ability to initiate new payments
`providers:read`	Access to the Capabilities (providers) endpoints

Request only the scopes your application needs. Requesting excessive scopes increases the blast radius of a compromised token.

Token Expiry

Tokens expire after 1800 seconds (30 minutes). To avoid authentication failures:

Track the expires_in value and request a new token before it expires
Implement a token refresh mechanism — re-request using the same credentials
Never hardcode tokens; always fetch them programmatically at startup and on expiry

If you receive a 401 Unauthorized response on a previously working request, your token has likely expired. Request a new one and retry.

Error Responses

Error	Meaning
`invalid_request`	Missing or malformed parameters
`invalid_client`	Invalid `clientId` or `clientSecret`
`invalid_scope`	One or more requested scopes are not permitted
`server_error`	The auth service is temporarily unavailable — retry with backoff

API concepts

Institutions

Payments

Reports

Authentication

Available Scopes

Token Expiry

Error Responses

​Available Scopes

​Token Expiry

​Error Responses

Available Scopes

Token Expiry

Error Responses