Skip to main content
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.
1

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
2

Request a token

Send a POST request to /api/v1/auth/token with your encoded credentials.Headers
Header
Value
AuthorizationBasic <base64-encoded-credentials>
Content-Typeapplication/x-www-form-urlencoded
Body (form-encoded)
Field
Value
grant_typeclient_credentials
scopeSpace-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
}
3

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:readRead access to payments and payment statuses
payments:writeAbility to initiate new payments
providers:readAccess 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_requestMissing or malformed parameters
invalid_clientInvalid clientId or clientSecret
invalid_scopeOne or more requested scopes are not permitted
server_errorThe auth service is temporarily unavailable — retry with backoff