# Request Access Token
source: https://developer.mastercard.com/consumer-clarity/documentation/clarity-in-clearing/cic-request-access-token/index.md

## Overview {#overview}

This article provides guidance on generating and managing the secure access tokens required to display digital receipts, including how to create the necessary client assertion, request the token through Mastercard's OAuth2 endpoint, and append it to the receipt URLs for a cardholder to use.

## Request Access Token {#request-access-token}

Requesting an access token is required for Digital Receipts URLs only. For privacy and security reasons, the Digital Receipts URL you receive in your clearing file can't be viewed by cardholders until an access token is appended to it. To request the token, you must make a **POST** request to the `/saat-auth/oauth2/token` endpoint.

* **Production domain:** `https://api.mastercard.com/saat-auth/oauth2/token`
* **Sandbox domain:** `https://sandbox.api.mastercard.com/saat-auth/oauth2/token`

Note: While you don't necessarily need to integrate with the Consumer Clarity API, you do need to obtain the keys required to request access tokens. For instructions on creating a Consumer Clarity API project and obtaining a consumer key, see our [Quick Start Guide](https://developer.mastercard.com/consumer-clarity/documentation/quick-start-guide/index.md).

For this request payload, you'll enter the `client_id` and `client_secret` that are part of the consumer key for the Consumer Clarity API project that you create. You must also generate the `client_assertion` token.

The token that's appended to the Digital Receipts URL expires 15 minutes after generation. If the application exposes these links for more than 15 minutes, you must re‑request the access token before the Digital Receipts URL link expires. Otherwise, a **Receipt expired** message is displayed to the cardholder when they select the link.

A token can be used on multiple Digital Receipts URLs during the time it is valid and not expired.

### Request access token through Oauth2 token endpoint {#request-access-token-through-oauth2-token-endpoint}

Refer to the sections below for a sample Request and Response that requests the access token
endpoint through OAUTH2 token endpoint.

**Resource**
`POST /oauth2/token`

**Request Payload**

    POST /saat-auth/oauth2/token HTTP/1.1
    Content-Type: application/x-www-form-urlencoded
    	onetime=false
    	&grant_type=client_credentials
    	&scope=com.mastercard.ethoca.clarity.receipt:receipt-service:receipt-service
    	&client_id=xxxxxxxxxx
    	&client_secret=xxxxxxx
    	&onetime=false
    	&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
    	&client_assertion=<Signed JWT token presented by consumer application>

* `client_id` is the part **before** the exclamation mark from the consumer key.
* `client_secret` is the part **after** the exclamation mark from the consumer key.

**Response Payload**

```json
{
  "access_token": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
  "token_type": "bearer",
  "expires_in": 900,
  "scope": "com.mastercard.ethoca. clarity.receipt:receipt-service:receiptservice"
}
```

This screenshot shows an Oauth2 token API sample request in Postman:

![Sample request for OAuth2 token](https://static.developer.mastercard.com/content/consumer-clarity/documentation/img/clearing/oauth2-token-sample-request.png)

## Generate Client Assertion Token {#generate-client-assertion-token}

**JWT Auth token contents**

```json
Header:
{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "consumer key" // e.g."3v6_I2nVeFoW73wjEpaxUkjM8FgtI3knTlhBtld8732f1a!a44d8bebc98c47ce95725f8d0e0855280000000000000000"
}
```

> Example `kid`:

**Payload:**

```json
Payload:
{
"sub": "not_available"
"nbf": 1569949649, // Not before Date(REQUIRED)
"exp": 1569950549, // Expiry date(REQUIRED)
"iat": 1569949649, // Issued At date(REQUIRED)
"jti": "e8ff3bfeb1ebd0f0bd54af711c10cc16", // Unique JWT id (REQUIRED)
}
```

### Private key for client assertion token generation {#private-key-for-client-assertion-token-generation}

Export Private Key from keystore (.p12) file

* The private key is used to generate Client Assertion Token.

* Run `openssl pkcs12 -info -in <the-keystore-for-the-env>.p12 -nodes -nocerts`
  and enter the keystore password. The private key should now be visible in the console output,
  as shown here:

![Private key example](https://static.developer.mastercard.com/content/consumer-clarity/documentation/img/clearing/private-key-example.png)

**Reference code for generating client assertion token (JavaScript):**

```javascript
var currentTime = +new Date(); // the current time in milliseconds
var issuedAtTimeSeconds = currentTime / 1000;
var expirationTimeSeconds = issuedAtTimeSeconds + 900;

var private_key = pm.environment.get("private_key");
var consumer_key = pm.environment.get("clientID") + "!" + pm.environment.get("clientSecret");

var randomJTI = "";

// create random oauth_nonce string
const random_source = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";

for (var i = 0; i < 32; i++) {
  randomJTI += random_source.charAt(
    Math.floor(Math.random() * random_source.length)
  );
}

// create Header and Payload objects
var header = { 
  alg: "RS256", 
  typ: "JWT", 
  kid: consumer_key
};

var payload = {
  sub: "not_available",
  nbf: Math.ceil(issuedAtTimeSeconds),
  exp: Math.ceil(expirationTimeSeconds),
  iat: Math.ceil(issuedAtTimeSeconds),
  jti: randomJTI
};

// prep the objects for a JWT
var sHeader = JSON.stringify(header);
var sPayload = JSON.stringify(payload);

var prvKey = KEYUTIL.getKey(private_key);

var sJWT = KJUR.jws.JWS.sign(header.alg, sHeader, sPayload, prvKey);

console.log("clientAssertionToken: " + sJWT);
```

## Append Token to a Digital Receipts URL {#append-token-to-a-digital-receipts-url}

After the access token is returned, you must append it to the Digital Receipts URL that was received in the test data response, for example: `<URL>?locale=<locale>&access_token=<access_token>`.

The locale (language--country combination) is associated with the location from which the request is made. Include a specific locale to determine the language displayed on the receipt.

**Supported languages:**

| Locale |      Description       |
|--------|------------------------|
| en-CA  | Canadian English       |
| en-GB  | United Kingdom English |
| en-US  | American English       |
| es-ES  | Castilian Spanish      |
| es-MX  | Mexican Spanish        |
| es-US  | Spanish-United States  |
| fr-CA  | Canadian French        |
| fr-FR  | French-France          |
| pt-BR  | Brazilian Portuguese   |
| pt-PT  | European Portuguese    |

## Next Steps {#next-steps}

Now that you have completed the steps to append a token to your Digital Receipts URL, review these other articles for guidance on using the appended URL in your organization.

* [Display Consumer Clarity](https://developer.mastercard.com/consumer-clarity/documentation/clarity-in-clearing/cic-display-clarity/index.md)
* [Test Clarity in Clearing Data](https://developer.mastercard.com/consumer-clarity/documentation/clarity-in-clearing/cic-testing/index.md)