Authentication

Utila API uses API bearer token to authenticate requests.

To generate an API token, you need to setup an API service account with its own private key in 3 steps:

1. Generate a private key or BYO private key

For first time try out, you can generate a private key on your local machine via:

openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:4096
openssl rsa -in private_key.pem -pubout -out public_key.pem

2. Setup a service account (API user) in Utila console

As an admin of a vault, navigate to Vault Settings → Service Accounts and create an account.
Place the public key you generated in the previous step.

Make sure the new service account role is approved by an admin.

For more info you can view Set up a service account guide.

3. Generate token with service account email and private key

You can either encode a JWT programmatically or via utila-cli tool (download it from resource center ).

import os
import jwt #use PyJWT module
import datetime

SERVICE_ACCOUNT_EMAIL = "SERVICE_ACCOUNT_EMAIL"

with open("private_key.pem", "r") as file:
	SERVICE_ACCOUNT_PRIVATE_KEY = file.read().strip()
  
token = jwt.encode(
  {
    "sub": SERVICE_ACCOUNT_EMAIL,
    "aud": "https://api.utila.io/",
    "exp": datetime.datetime.utcnow() + datetime.timedelta(hours=1)
  },
  SERVICE_ACCOUNT_PRIVATE_KEY.replace('\\n', '\n'),  # Ensure correct key format
  algorithm="RS256"
)
print("Generated Token:", token)

import * as fs from 'fs';
import * as jwt from 'jsonwebtoken';
import * as path from 'path';

const SERVICE_ACCOUNT_EMAIL = "SERVICE_ACCOUNT_EMAIL";
const privateKeyPath = path.join(__dirname, 'private_key.pem');

const SERVICE_ACCOUNT_PRIVATE_KEY = fs.readFileSync(privateKeyPath, 'utf8').trim();

const token = jwt.sign(
  {
    sub: SERVICE_ACCOUNT_EMAIL,
    aud: "https://api.utila.io/",
    exp: Math.floor(Date.now() / 1000) + 60 * 60 // Expires in 1 hour
  },
  SERVICE_ACCOUNT_PRIVATE_KEY.replace(/\\n/g, '\n'), // Ensure correct key format
  { algorithm: "RS256" }
);

console.log("Generated Token:", token);

export UTILA_SA_PRIVATE_KEY=$(cat private_key.pem)
export UTILA_ACCOUNT="SERVICE_ACCOUNT_EMAIL"
./utilacli auth print-access-token