> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getkard.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getkard.com/_mcp/server.

# Authentication

## Kard API

The Kard API supports authentication via OAuth2.0's client credentials. Issuer client will be provided
**`client_id`** and **`client_secret`** by Kard.

### Kard Authentication API v2

Use the new Kard Authentication API endpoint. Each client will have their own dedicated subdomain,
which will be provided by Kard.

The API follows OAuth2.0 client credentials flow and requires:

* **Authorization header**: Basic authentication with base64 encoded `{client_id}:{client_secret}`
* **Content-Type header**: Must be set to `application/x-www-form-urlencoded`
* **Request body**: Form data with `grant_type=client_credentials`

```javascript
const axios = require('axios');

const config = {
    method: 'POST',
    url: 'https://{your-client-subdomain}.getkard.com/v2/auth/token',
    headers: {
        'Authorization': 'Basic {base64_encoded_client_id:client_secret}',
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    data: 'grant_type=client_credentials'
};

axios(config)
.then(function (response) {
    console.log(JSON.stringify(response.data));
})
.catch(function (error) {
    console.log(error);
});
```

> **Note**
>
> Replace `{your-client-subdomain}` with the subdomain provided by Kard for your organization.
> The returned access token must be used in the `Authorization` header as a bearer token
> in subsequent requests.

### Multi-Issuer Authentication (Beta)

> **Note**
>
> This feature is currently in **Beta**. If you are interested in using this feature, please contact your Kard representative.

If you manage multiple issuers on the Kard platform, you can scope your auth token to a specific issuer by including the `X-Kard-Target-Issuer` header in your token request. The response is identical to a standard authentication request, but the returned access token will be locked to the issuer specified in the header.

```javascript
const axios = require('axios');

const config = {
    method: 'POST',
    url: 'https://{your-client-subdomain}.getkard.com/v2/auth/token',
    headers: {
        'Authorization': 'Basic {base64_encoded_client_id:client_secret}',
        'Content-Type': 'application/x-www-form-urlencoded',
        'X-Kard-Target-Issuer': '{target_issuer_id}'
    },
    data: 'grant_type=client_credentials'
};

axios(config)
.then(function (response) {
    console.log(JSON.stringify(response.data));
})
.catch(function (error) {
    console.log(error);
});
```

Example response:

```json
{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    "token_type": "Bearer",
    "expires_in": 3600
}
```

Any subsequent API calls made with this token will be scoped to the specified issuer. If you need to interact with a different issuer, request a new token with the corresponding `X-Kard-Target-Issuer` value.

## Response Examples

The API returns standard HTTP status codes:

* **200**: Successful authentication with access token
* **400**: Bad request (missing Authorization header or invalid grant\_type)
* **401**: Unauthorized (invalid credentials)
* **404**: Not found (client not found)
* **500**: Internal server error

Example Successful Response:

```json
{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    "token_type": "Bearer",
    "expires_in": 3600
}
```

### Direct Cognito (Deprecated)

> **Warning**
>
> **DEPRECATED**: The direct Cognito authentication method is deprecated and will be discontinued soon.
> Please migrate to the new Authentication API v2 above.

* `GET Session Token` request in root directory
* baseURL: `https://test-rewards-api.auth.us-east-1.amazoncognito.com`
* `{clientHash}`: base64 encoded copy of `{client_id}:{client_secret}`, provided in the postman\_environment.json.

```javascript
const axios = require('axios');

const config = {
    method: 'POST',
    url: 'https://test-rewards-api.auth.us-east-1.amazoncognito.com/oauth2/token?grant_type=client_credentials',
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Authorization': 'Basic {clientHash}'
    }
};

axios(config)
.then(function (response) {
    console.log(JSON.stringify(response.data));
})
.catch(function (error) {
    console.log(error);
});
```

Example response:

```json
{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    "token_type": "Bearer",
    "expires_in": 3600
}
```