> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kashimi.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate your application using OAuth 2.0 Client Credentials to obtain a Bearer token for all API requests.

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.

<Steps>
  <Step title="Encode your credentials">
    Combine your `clientId` and `clientSecret` with a colon, then Base64-encode the result:

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

    <CodeGroup>
      ```bash Terminal theme={null}
      echo -n "your-client-id:your-client-secret" | base64
      ```
    </CodeGroup>
  </Step>

  <Step title="Request a token">
    Send a `POST` request to `/api/v1/auth/token` with your encoded credentials.

    **Headers**

    | <div align="left">**Header**</div> | <div align="left">**Value**</div>    |
    | ---------------------------------- | ------------------------------------ |
    | `Authorization`                    | `Basic <base64-encoded-credentials>` |
    | `Content-Type`                     | `application/x-www-form-urlencoded`  |

    **Body (form-encoded)**

    | <div align="left">**Field**</div> | <div align="left">**Value**</div>                                          |
    | --------------------------------- | -------------------------------------------------------------------------- |
    | `grant_type`                      | `client_credentials`                                                       |
    | `scope`                           | Space-separated list of scopes (see [Available Scopes](#available-scopes)) |

    <CodeGroup>
      ```bash cURL theme={null}
      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"
      ```
    </CodeGroup>

    A successful response returns a JSON object:

    ```json theme={null}
    {
      "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
      "token_type": "Bearer",
      "expires_in": 1800
    }
    ```
  </Step>

  <Step title="Use the token">
    Pass the `access_token` in the `Authorization` header of every subsequent API request:

    ```
    Authorization: Bearer <access_token>
    ```
  </Step>
</Steps>

***

## Available Scopes

| <div align="left">**Scope**</div> | <div align="left">**Description**</div>          |
| --------------------------------- | ------------------------------------------------ |
| `payments:read`                   | Read access to payments and payment statuses     |
| `payments:write`                  | Ability to initiate new payments                 |
| `providers:read`                  | Access to the Capabilities (providers) endpoints |

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

***

## 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

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

***

## Error Responses

| <div align="left">**Error**</div> | <div align="left">**Meaning**</div>                              |
| --------------------------------- | ---------------------------------------------------------------- |
| `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 |