Authentication

Paperbox provisions both an API Key (which can be limited to specific IPs) and a Private RSA Key (which is used to generate JSON Web Tokens). Every API consumer is responsible for securing these credentials and can be rotated upon request.

JWT generation examples

Py

pip install PyJWT

from enum import Enum
import time
import jwt


class Environment(str, Enum):
    ACCEPTANCE = "acc"
    PRODUCTION = "prd"


def generate_jwt(
    private_key_path="path/to/private-key.pem",
    tenant_id: str = "tenant-id",
    env: Environment = Environment.PRODUCTION,
    expiry_length=3600,
) -> str:
    """Generates a signed JSON Web Token using a private key.

    Args:
        private_key_path (str): Path to the private key file
        tenant_id (str): The tenant ID
        env (Environment): The environment
        expiry_length (int): The length of time in seconds before the token expires

    Returns:
        str: The signed JSON Web Token
    """
    with open(private_key_path, "r") as file:
        private_key = file.read()

    now = int(time.time())

    email = f"{tenant_id}@paperbox-{env}.iam.gserviceaccount.com"

    # Build payload
    payload = {
        "iat": now,
        "exp": now + expiry_length,
        "iss": email,
        "aud": f"https://integration.{env}.paperbox.ai",
        "sub": email,
        "email": email,
    }

    return jwt.encode(payload, private_key, algorithm="RS256")


if __name__ == "__main__":
    print(generate_jwt("private_key.pem", "tenant_id", Environment.PRODUCTION))

Rb

require 'openssl'
require 'jwt'

class Environment
  ACCEPTANCE = "acc"
  PRODUCTION = "prd"
end

def generate_jwt(
  private_key_path = "path/to/private-key.pem",
  tenant_id = "tenant-id",
  env = Environment::PRODUCTION,
  expiry_length = 3600
)
  private_key = OpenSSL::PKey::RSA.new(File.read(private_key_path))
  now = Time.now.to_i
  email = "#{tenant_id}@paperbox-#{env}.iam.gserviceaccount.com"

  payload = {
    iat: now,
    exp: now + expiry_length,
    iss: email,
    aud: "https://integration.#{env}.paperbox.ai",
    sub: email,
    email: email
  }

  JWT.encode(payload, private_key, 'RS256')
end

if __FILE__ == $0
  puts generate_jwt("private_key.pem", "tenant_id", Environment::PRODUCTION)
end

C#

using System;
using System.IO;
using System.IdentityModel.Tokens.Jwt;
using Microsoft.IdentityModel.Tokens;
using System.Text;
using System.Collections.Generic;

public class JwtGenerator
{
    public enum Environment
    {
        ACCEPTANCE,
        PRODUCTION
    }

    private static readonly Dictionary<Environment, string> EnvironmentValues = new Dictionary<Environment, string>
    {
        { Environment.ACCEPTANCE, "acc" },
        { Environment.PRODUCTION, "prd" }
    };

    public static string GenerateJwt(
        string privateKeyPath = "path/to/private-key.pem",
        string tenantId = "tenant-id",
        Environment env = Environment.PRODUCTION,
        int expiryLength = 3600)
    {
        var privateKey = File.ReadAllText(privateKeyPath);
        var securityKey = new RsaSecurityKey(Encoding.UTF8.GetBytes(privateKey));
        var credentials = new SigningCredentials(securityKey, SecurityAlgorithms.RsaSha256);

        var now = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
        var envValue = EnvironmentValues[env];
        var email = $"{tenantId}@paperbox-{envValue}.iam.gserviceaccount.com";

        var payload = new JwtPayload
        {
            { "iat", now },
            { "exp", now + expiryLength },
            { "iss", email },
            { "aud", $"https://integration.{envValue}.paperbox.ai" },
            { "sub", email },
            { "email", email }
        };

        var token = new JwtSecurityToken(new JwtHeader(credentials), payload);
        return new JwtSecurityTokenHandler().WriteToken(token);
    }

    public static void Main(string[] args)
    {
        Console.WriteLine(GenerateJwt("private_key.pem", "tenant_id", Environment.PRODUCTION));
    }
}

Ts

import * as fs from "fs";
import * as jwt from "jsonwebtoken";

enum Environment {
  ACCEPTANCE = "acc",
  PRODUCTION = "prd",
}

function generateJwt(
  privateKeyPath: string = "path/to/private-key.pem",
  tenantId: string = "tenant-id",
  env: Environment = Environment.PRODUCTION,
  expiryLength: number = 3600
): string {
  const privateKey = fs.readFileSync(privateKeyPath, "utf8");
  const now = Math.floor(Date.now() / 1000);
  const email = `${tenantId}@paperbox-${env}.iam.gserviceaccount.com`;

  const payload = {
    iat: now,
    exp: now + expiryLength,
    iss: email,
    aud: `https://integration.${env}.paperbox.ai`,
    sub: email,
    email: email,
  };

  return jwt.sign(payload, privateKey, { algorithm: "RS256" });
}

console.log(
  generateJwt("private_key.pem", "tenant_id", Environment.PRODUCTION)
);

Js

const fs = require("fs");
const jwt = require("jsonwebtoken");

const Environment = {
  ACCEPTANCE: "acc",
  PRODUCTION: "prd",
};

function generateJwt(
  privateKeyPath = "path/to/private-key.pem",
  tenantId = "tenant-id",
  env = Environment.PRODUCTION,
  expiryLength = 3600
) {
  const privateKey = fs.readFileSync(privateKeyPath, "utf8");
  const now = Math.floor(Date.now() / 1000);
  const email = `${tenantId}@paperbox-${env}.iam.gserviceaccount.com`;

  const payload = {
    iat: now,
    exp: now + expiryLength,
    iss: email,
    aud: `https://integration.${env}.paperbox.ai`,
    sub: email,
    email: email,
  };

  return jwt.sign(payload, privateKey, { algorithm: "RS256" });
}

console.log(
  generateJwt("private_key.pem", "tenant_id", Environment.PRODUCTION)
);