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

1
const axios = require('axios');
2
3
const config = {
4
    method: 'POST',
5
    url: 'https://{your-client-subdomain}.getkard.com/v2/auth/token',
6
    headers: {
7
        'Authorization': 'Basic {base64_encoded_client_id:client_secret}',
8
        'Content-Type': 'application/x-www-form-urlencoded'
9
    },
10
    data: 'grant_type=client_credentials'
11
};
12
13
axios(config)
14
.then(function (response) {
15
    console.log(JSON.stringify(response.data));
16
})
17
.catch(function (error) {
18
    console.log(error);
19
});

Multi-Issuer Authentication (Beta)

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.

1
const axios = require('axios');
2
3
const config = {
4
    method: 'POST',
5
    url: 'https://{your-client-subdomain}.getkard.com/v2/auth/token',
6
    headers: {
7
        'Authorization': 'Basic {base64_encoded_client_id:client_secret}',
8
        'Content-Type': 'application/x-www-form-urlencoded',
9
        'X-Kard-Target-Issuer': '{target_issuer_id}'
10
    },
11
    data: 'grant_type=client_credentials'
12
};
13
14
axios(config)
15
.then(function (response) {
16
    console.log(JSON.stringify(response.data));
17
})
18
.catch(function (error) {
19
    console.log(error);
20
});

Example response:

1
{
2
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
3
    "token_type": "Bearer",
4
    "expires_in": 3600
5
}

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:

1
{
2
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
3
    "token_type": "Bearer",
4
    "expires_in": 3600
5
}

Direct Cognito (Deprecated)

• 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.

1
const axios = require('axios');
2
3
const config = {
4
    method: 'POST',
5
    url: 'https://test-rewards-api.auth.us-east-1.amazoncognito.com/oauth2/token?grant_type=client_credentials',
6
    headers: {
7
        'Content-Type': 'application/x-www-form-urlencoded',
8
        'Authorization': 'Basic {clientHash}'
9
    }
10
};
11
12
axios(config)
13
.then(function (response) {
14
    console.log(JSON.stringify(response.data));
15
})
16
.catch(function (error) {
17
    console.log(error);
18
});

Example response:

1
{
2
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
3
    "token_type": "Bearer",
4
    "expires_in": 3600
5
}