At the core of our public API is a security mechanism that allows Coursepath to trust the requests it gets from your systems. For this we use a technology called JSON Web Token (JWT). We use it in our REST-API and for Single Sign-On integrations.
JWT is an open standard that is being driven by the international standards body IETF. Check out this article for a nice JWT introduction for programmers: The Anatomy of a JSON Web Token.
Building a JWT token for Coursepath integrations is pretty simple. We only require a small part of the spec. Please follow these guidelines:
email
claim is required. This is the user for whom you make the request.iat
claim is required. This identifies the time at which your JWT was created. If your token is older than a couple of minutes, we will reject it.jti
claim is required. This is a unique identifier for your token. You can use tokens only once.HS256
is supported. Tokens with other algorithms are rejected.There are many open source JWT libraries available to help you construct the token. However, since our implementation is very straightforward, you could also do it yourself. Here's an example in plain PHP:
function jwt_token($email, $api_key)
{
// create the header part:
$header = array('typ' => 'JWT', 'alg' => 'HS256');
$base64_header = base64url_encode(json_encode($header));
// create the claims part:
$claims = array('jti' => mt_rand(), 'iat' => time(), 'email' => $email);
$base64_claims = base64url_encode(json_encode($claims));
// create the signature:
$hash = hash_hmac('SHA256', $base64_header . '.' . $base64_claims, $api_key, true);
$base64_signature = base64url_encode($hash);
// concatenate the three parts:
$jwt = $base64_header . '.' . $base64_claims . '.' . $base64_signature;
return $jwt;
}
function base64url_encode($data)
{
return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
}
Tip: you can validate the syntax of your generated token here: https://jwt.io.