The Victor Platform leverages JSON Web Tokens (JWTs) to identify clients and to ensure the security of requests. In order to generate a JWT, the following requirements must be met:

• API Key must be generated from the client account
• Securely stored private key must be created (this client private key is not recoverable after initial generation, so don't lose it!)

In order to generate your API Key, login to the Client Portal, navigate to My Organization from the Home menu and select the Developer menu item from left-hand options.

💡

API Key Types

Note: there are two types of API keys that can be created:

1. OAuth (Preferred): By checking the "Create OAuth Key" within the "New API Key" modal, an OAuth API Key will be created. This is the preferred method of authentication and the instructions for using this key can be found in the below section, "Using an OAuth Token".
2. Client Generated JWT (Deprecated): This key type is created by leaving the "Create OAuth Key" checkbox blank. This method of authentication is deprecated, instructions for using a client generated JWT can be found in the below section, "Using a Client Generated JWT."

Developers Page

New API Key Modal

Using an OAuth Token

After generating an OAuth API Key, the client ID and client secret can be used to obtain a valid JWT token. Note the token will automatically expire and no longer be valid after the expires epoch timestamp (in milliseconds) returned in the access token response has been reached. Once a token has expired, a new token must be requested.

Requesting an Access Token

A JWT access token can be requested using the /v2/auth/token API endpoint by providing the client ID and client secret in the request body. A Sample request and sample response are shown below:

Sample Request

{ 
  "client_id": "<your-client-id>",
  "client_secret": "<your-secret>"
}

Sample Response

{ 
  "access_token": "<access-token-value>", 
  "token_type": "<token-type e.g. Bearer>", 
  "expires": 1683308669000 
}

Using the Access Token

The access token must be included in all requests to the Victor API. To use the access token, include it in the request as an Authorization header prefixed by the token_type e.g. Bearer as shown in the example below.

--header 'Authorization:  Bearer <access-token-here>'

Using a Client Generated JWT (Deprecated)

After generating an API Key, the API code and private key can be used to generate a JWT token using the following steps:

Setting the Token Header

In the Header section of your JWT, use the following:

{
    "alg":  "RS512",
    "typ":  "JWT"
}

Use the following details when generating a client JWT:

💡

Info

Issuer: victor-api
Signature Algorithm: RSA-512
Subject: client-api-key

Creating the Claims

The Payload section of your JWT contains a set of claims. The JWT specification defines seven Registered Claim Names, which are the standard fields commonly used in tokens. For your JWT with Victor, the following claims and values are required:

{
    "sub":  "65b6f047-c618-485b-a878-833ac3649ec2" (your-api-key),
    "iss":  "victor-api",
    "iat":  1623697929 (issued at timestamp),
    "exp":  1623698229 (expiration timestamp)
}

It's important to note that an expiration on the token is required. Ideally, a new token is generated for each request when used in Production.

🚧

Heads Up!

The maximum expiration time accepted on Production is 300 seconds (iat timestamp + 300, or 5 minutes).

The maximum expiration time on Staging is 3600 seconds (iat timestamp + 3600, or 60 minutes).

Generating and Signing the Token

You can generate and sign a JWT using multiple methods. A good resource for manually generating and/or verifying JWTs is JWT.io. Below is a code snippet that shows generating and signing a JWT in Java using the Java JWT Library:

import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;

import java.security.KeyFactory;
import java.security.PrivateKey;
import java.security.spec.PKCS8EncodedKeySpec;
import java.util.Base64;
import java.util.Date;

public class JWTGenerator {

  public String generateJWT() throws Exception {
    Date createdDate = new Date();
    Date expirationDate = new Date(createdDate.getTime() + 300);
    String privateKeyString = "-----BEGIN PRIVATE KEY-----\n"
      + "Private key\n"
      + "-----END PRIVATE KEY-----";
    String keyArray = new String(privateKeyString)
      .replace("-----BEGIN PRIVATE KEY-----", "")
      .replace("-----END PRIVATE KEY-----", "")
      .replaceAll("\\s", "");
    byte[] raw = Base64.getDecoder().decode(keyArray);
    KeyFactory keyFactory = KeyFactory.getInstance("RSA");
    PrivateKey privateKey = keyFactory.generatePrivate(new PKCS8EncodedKeySpec(raw));
    String jwtToken = Jwts.builder()
                          .setSubject("API KEY")
                          .setIssuer("victor-api")
                          .setIssuedAt(createdDate)
                          .setExpiration(expirationDate)
                          .signWith(SignatureAlgorithm.RS512, privateKey)
                          .compact();
    return jwtToken;
  }

Using the Token

Once the JWT is generated, it must be included in an Authorization header within each request, prefixed with the word Token as shown below:

--header 'Authorization:  Token <jwt-string-here>'