Authentication

The API requires a Bearer authentication header. We recommend signing a short-lived JWT token on your client.

What is a JWT token?

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.

Although JWTs can be encrypted to also provide secrecy between parties, we will focus on signed tokens. Signed tokens can verify the integrity of the claims contained within it, while encrypted tokens hide those claims from other parties. When tokens are signed using public/private key pairs, the signature also certifies that only the party holding the private key is the one that signed it.

How to create a token?

You can use any JWT-library that is capable to generate, sign and encode a token. You received the following credentials from TapRaise:

1. Account email address

2. Private key ID

3. Private key (PKCS8)

Please securely store the private key data, as it grants access to your data.

Use the header and claims as described below to create a JWT that is accepted by the API.

Headers and Claims

Header

• kid (key id): What key was used for signature, use private key ID as provided.

• alg (algorithm): Algorithm used for signature, always RS256.

Custom claims

• email (email address): The account email address as provided.

Reserved claims

• iss (issuer): Issuer of the JWT, also the account email address as provided.

• iat (issued at time): Time at which the JWT was issued; can be used to determine age of the JWT.

• exp (expiration time): Time after which the JWT expires.

Examples

Node with jose

const jose = require('jose');

// Provided by TapRaise
const algorithm = 'RS256';
const privateKey = '-----BEGIN PRIVATE KEY-----.....-----END PRIVATE KEY-----';
const privateKeyId = '03e718b3..........ab4583782';
const email = '[e-mail]';

const customClaims = {
  email: email,
};

const header = {
  alg: algorithm,
  kid: privateKeyId,
};

const jwt = new jose.SignJWT(customClaims)
  .setProtectedHeader(header)
  .setIssuer(email)
  .setIssuedAt()
  .setExpirationTime('1h'); // Valid for 1 hour

(async () => {
  const importedKey = await jose.importPKCS8(privateKey, algorithm);
  const signed = await jwt.sign(importedKey);

  console.log(jwt); // token content
  console.log(signed); // signed token, used as Bearer token.
})();

Python with pyjwt

from datetime import datetime
import jwt

algorithm = "RS256"
private_key = "-----BEGIN PRIVATE KEY-----.....-----END PRIVATE KEY-----"
private_key_id = "03e718b3..........ab4583782"
client_email = "[e-mail]"

headers = {
    "alg": algorithm,
    "kid": private_key_id
}

payload = {
    "email": client_email,
    "iss": client_email,
    "iat": int(datetime.now().timestamp()),
    "exp": int(datetime.now().timestamp() + 3600)
}

encoded = jwt.encode(payload, private_key, algorithm, headers=headers)

print(encoded) # signed token, used as Bearer token

CLI

Creating a JWT with jwt-cli

jwt encode --alg RS256 --kid replaceThisWithYourPrivateKeyId --iss [e-mail] --exp=1h --secret=@/path/to/private_key.pem '{"email": "[e-mail]"}'

Decoding a JWT with jwt-cli

jwt decode replaceThisWithYourJWT

Resources

• jwt.io/introduction - Introduction to JWT's

• jwt.io/libraries - Libraries

• https://github.com/mike-engel/jwt-cli - CLI tool to decode and encode JWTs

• cloud.google.com/api-gateway/docs/authenticate-service-account - Other examples