Authentication

The Loyalty API is made up of three APIs, each authenticated differently:

Partner ID

Every Loyalty API request identifies your program with its partner ID. To find it, sign in to the Admin Console and go to General >> Settings.

API keys

The Admin API and the UI API require an API key. To create one, go to General >> API Keys in the Admin Console, click Create API Key, enter a name and a description for the key, and click Create API Key again. The new key is listed on the page. We highly recommend creating a separate API key for each integration.

From the list, you can:

• Show or hide a key (the eye icon). You're asked to authenticate before the key is shown.
• Copy a key.
• Edit a key's name and description.
• Deactivate a key. Requests that use a deactivated key fail with an authentication error. A deactivated key can be activated again.
• Delete a deactivated key, after confirming. Deleting a key is permanent.

Only admins with full access can see the API keys section, every action is logged in the audit trail, and each program can have at most 20 API keys.

Integrations that use the default API key keep working. To switch one to a new key, create the key and replace the default key in the integration. If you use a new key for the UI APIs or the Authentication JS, you also need to send the key's API key identifier, so that TrueLoyal knows which key signed the tokens (see UI API).

Admin API

Send your API key and partner ID in the headers of every request:

api-key: <your-api-key>
partner-id: <your-partner-id>

UI API

The UI API is designed for the front end, for example to build your own loyalty dashboard. Instead of the API key, requests carry a JSON Web Token (JWT) signed with the API key, along with your partner ID.

To sign the token, you need an API key and its API key identifier, both listed under General >> API Keys. The token's claims are:

• sub: the API key identifier. Not needed when the token is signed with the default API key.
• member_id: the unique identifier of the logged-in member.
• exp: the Unix timestamp (in seconds) after which the token expires.

Sign the token with HS256 and the API key as the secret:

require "jwt"

secret = "your-api-key"
claims = {
  "sub" => "api-key-identifier",
  "member_id" => "unique-id",
  "exp" => 1635862400,
}

puts JWT.encode(claims, secret, "HS256")

import jwt

secret = "your-api-key"
claims = {
    "sub": "api-key-identifier",
    "member_id": "unique-id",
    "exp": 1635862400,
}

print(jwt.encode(claims, secret, algorithm="HS256"))

<?php
function base64url(string $data): string
{
    return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
}

$secret = 'your-api-key';
$header = ['alg' => 'HS256', 'typ' => 'JWT'];
$claims = [
    'sub' => 'api-key-identifier',
    'member_id' => 'unique-id',
    'exp' => 1635862400,
];

$unsigned = base64url(json_encode($header)) . '.' . base64url(json_encode($claims));
echo $unsigned . '.' . base64url(hash_hmac('sha256', $unsigned, $secret, true));

// Maven: com.auth0:java-jwt
import com.auth0.jwt.JWT;
import com.auth0.jwt.algorithms.Algorithm;
import java.time.Instant;

public class JWTApplication {
    public static void main(String[] args) {
        String secret = "your-api-key";
        String token = JWT.create()
                .withSubject("api-key-identifier")
                .withClaim("member_id", "unique-id")
                .withExpiresAt(Instant.ofEpochSecond(1635862400))
                .sign(Algorithm.HMAC256(secret));
        System.out.println(token);
    }
}

Then send the JWT and your partner ID in the headers of every request:

access-token: <jwt>
partner-id: <your-partner-id>

Guest API

The Guest API is also designed for the front end, but only returns basic program details, so requests only need your partner ID, in the partner-id header:

partner-id: <your-partner-id>

Allowing front-end origins

Before you call the UI API or the Guest API from a browser, add your site's origin to the CORS settings:

1. Sign in to the Admin Console.
2. Go to the General section.
3. Select Settings.
4. Find CORS Settings.
5. Add the origin URL. To allow several domains, separate them with commas, without spaces.
6. Save your changes.