Customer token

A customer token is part of the advanced customer authentication process. Marketing APIs use it instead of customer IDs. The token contains encoded customer IDs and a signature. When the Marketing API receives a customer token, it verifies the signature first and processes the request only if the signature is valid.

To learn more about advanced authentication, see authentication in App inbox.

How it works

Customer tokens must be generated by a party that can securely verify the customer's identity. Usually, this is the website or application backend during login. After the customer's identity is verified (for example, with a password, third-party authentication, or single sign-on), the backend should generate the Marketing customer token and send it to the device running the Marketing JavaScript or mobile SDK.

Customer identity verification

Customer tokens must be generated by a party that can also verify the customer's identity. Marketing can't provide an API to generate customer tokens. Doing so would break the security of advanced authentication, because the Marketing API can't verify whether a device or API request is allowed to use a particular customer ID.

Customer token generation

The customer token is encoded using the JSON web token standard. For the Marketing API to decode the token and verify its customer IDs, the token must follow a specific schema. The following sections describe the required parameters and their format.

Requirements

• JWT header schema
• JWT payload schema
• JWT signature

Header schema

Payload schema

Signature

To create the signature, see JWS Message Signature or MAC Computation. Advanced customer authentication supports the HS256 signing scheme.

Signing secret

The HS256 signing scheme requires a shared secret to generate and validate the signature. Advanced customer authentication uses Marketing private API keys for this purpose.

Generate customer tokens

1. Make sure your project has a private API group. You need it to get the secret API key.
2. Add a private API group key, and store its value securely. You can't recover the value later. The key consists of an API key ID and an API secret.

3. Generate your customer token. Use the API Key ID value in the kid field of the JWT header, and use the SHA-256 checksum of the API Secret value to create the JWT signature. See the following example.

   ❗️

   Warning

   Never share the API secret or store it on an end-user device, such as a mobile app or web browser.

4. Encode and sign the token:

   1. Create the SHA-256 checksum of the API secret.
   2. Encode the JWT header and JWT payload, as specified in the header and payload schemas, as JSON strings.
   3. Convert both to unpadded base64url, and join them with a dot (.).
   4. Sign the result of step 3 using the HS256 (HMAC with SHA-256) signing method. Use the SHA-256 checksum from step 1 as the key.
   5. Encode the signature as unpadded base64url, and append it to the result of step 3. Use a dot (.) as the separator.

The result is your customer token.

Generate customer token with PyJWT

The following example generates a customer token using the PyJWT library.

import hashlib
import jwt


def customer_token(customer_ids: dict, api_key_id: str, api_key_secret: str, expire_time: int=None) -> str:
    header_data = {
        'alg': 'HS256',
        'typ': 'JWT',
        'kid': api_key_id,
    }
    claims_data = {
        'sub': customer_ids,
    }

    if expire_time:
        claims_data['exp']: expire_time

    # note: we must use SHA256 checksum of the api_key_secret as signing secret, not api_key_secret directly
    signing_key = hashlib.sha256(api_key_secret.encode()).hexdigest()
    return jwt.encode(claims_data, signing_key, headers=header_data, algorithm='HS256')

token = customer_token(
    customer_ids={"registered":"[email protected]"},
    api_key_id="example-api-key-id",
    api_key_secret="example-api-secret",
)
print(token)
# expected result:
# eyJhbGciOiJIUzI1NiIsImtpZCI6ImV4YW1wbGUtYXBpLWtleS1pZCIsInR5cCI6IkpXVCJ9.eyJzdWIiOnsicmVnaXN0ZXJlZCI6ImpvaG4uZG9lQGV4YW1wbGUuY29tIn19.e2spIFhcuoSuvXKWoquGBQNC35BAq_ixFCcYEGe0Roo