Authentication

PrimeVault authenticates every external API request with an API-user key and a short-lived ES256 bearer token. Authentication is organization-scoped: credentials may access only the organization and permissions assigned to that API user.

Base URL

https://api.primevault.com

All endpoint paths are relative to this URL.

Recommended: use the JavaScript SDK

The SDK signs the exact request URL and JSON body, adds the required headers, and maps HTTP failures to typed errors.

import { APIClient } from "@primevault/js-api-sdk";

const apiClient = new APIClient(
  process.env.PRIMEVAULT_API_KEY!,
  "https://api.primevault.com",
  process.env.PRIMEVAULT_ACCESS_PRIVATE_KEY!,
);

Create the client only in a trusted server environment. Never embed the API key or access private key in browser, mobile, or other distributed client code.

Generate a bearer token manually

Generate tokens manually only when you can’t use the official SDK to send the request. The token is request-bound: generate it from the relative URL path and the same body object that will be sent, then create a new token for the next request. The examples below accept either a PEM private key or a hex-encoded PKCS#8 DER private key. They intentionally use the DER-encoded ECDSA signature produced by the PrimeVault SDKs. Do not replace the signing step with a generic JWT helper unless it can emit that signature format.

import {
  createHash,
  createPrivateKey,
  createSign,
  randomUUID,
} from "node:crypto";

const sortKeys = (value) => {
  if (Array.isArray(value)) return value.map(sortKeys);
  if (value && typeof value === "object") {
    return Object.fromEntries(
      Object.keys(value)
        .sort()
        .map((key) => [key, sortKeys(value[key])]),
    );
  }
  return value;
};

const base64url = (value) => Buffer.from(value).toString("base64url");

function generatePrimeVaultToken(apiKey, privateKey, urlPath, body = {}) {
  const now = Math.floor(Date.now() / 1000);
  const bodyHash = createHash("sha256")
    .update(JSON.stringify(sortKeys(body)))
    .digest("hex");

  const header = { alg: "ES256", typ: "JWT" };
  const payload = {
    iat: now,
    exp: now + 120,
    urlPath,
    userId: apiKey,
    body: bodyHash,
    jti: randomUUID(),
  };

  const signingInput = [header, payload]
    .map((part) => base64url(JSON.stringify(sortKeys(part))))
    .join(".");

  const trimmedKey = privateKey.trim();
  const key = trimmedKey.startsWith("-----BEGIN")
    ? createPrivateKey(trimmedKey)
    : createPrivateKey({
        key: Buffer.from(trimmedKey, "hex"),
        format: "der",
        type: "pkcs8",
      });

  const signer = createSign("SHA256");
  signer.update(signingInput);
  signer.end();

  return `${signingInput}.${base64url(signer.sign(key))}`;
}

const apiKey = process.env.PRIMEVAULT_API_KEY;
const privateKey = process.env.PRIMEVAULT_ACCESS_PRIVATE_KEY;
const urlPath = "/api/external/vaults/";
const token = generatePrimeVaultToken(apiKey, privateKey, urlPath);

const headers = {
  Authorization: `Bearer ${token}`,
  "Api-Key": apiKey,
  Accept: "application/json",
};

import base64
import hashlib
import json
import os
import time
import uuid
from typing import Optional

from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import ec


def base64url(value: bytes) -> str:
    return base64.urlsafe_b64encode(value).decode("ascii")


def generate_primevault_token(
    api_key: str,
    private_key: str,
    url_path: str,
    body: Optional[dict] = None,
) -> str:
    now = int(time.time())
    canonical_body = json.dumps(
        body or {},
        sort_keys=True,
        separators=(",", ":"),
        ensure_ascii=False,
    )

    header = {"alg": "ES256", "typ": "JWT"}
    payload = {
        "iat": now,
        "exp": now + 120,
        "urlPath": url_path,
        "userId": api_key,
        "body": hashlib.sha256(canonical_body.encode()).hexdigest(),
        "jti": str(uuid.uuid4()),
    }

    signing_input = ".".join(
        base64url(
            json.dumps(
                part,
                sort_keys=True,
                separators=(",", ":"),
                ensure_ascii=False,
            ).encode()
        )
        for part in (header, payload)
    )

    trimmed_key = private_key.strip()
    if trimmed_key.startswith("-----BEGIN"):
        key = serialization.load_pem_private_key(
            trimmed_key.encode(),
            password=None,
        )
    else:
        key = serialization.load_der_private_key(
            bytes.fromhex(trimmed_key),
            password=None,
        )

    signature = key.sign(
        signing_input.encode(),
        ec.ECDSA(hashes.SHA256()),
    )
    return f"{signing_input}.{base64url(signature)}"


api_key = os.environ["PRIMEVAULT_API_KEY"]
private_key = os.environ["PRIMEVAULT_ACCESS_PRIVATE_KEY"]
url_path = "/api/external/vaults/"
token = generate_primevault_token(api_key, private_key, url_path)

headers = {
    "Authorization": f"Bearer {token}",
    "Api-Key": api_key,
    "Accept": "application/json",
}

For POST and PUT requests, construct the body once, pass that object to the token helper, and send the same object as JSON without mutating its keys or values between signing and transmission.

Required headers

Header	Value	Purpose
`Authorization`	`Bearer <signed JWT>`	Short-lived ES256 token bound to the exact request path and, for writes, the exact JSON body.
`Api-Key`	API-user key	Identifies the API user and organization.
`version`	Installed SDK version	Identifies the client contract. Added by the SDK.
`Content-Type`	`application/json`	Required when a JSON request body is sent.
`Accept`	`application/json`	Requests a JSON response. Added by the SDK.

Header names are case-insensitive at the HTTP layer, but use the spelling above in examples and diagnostics.

How request signing works

Build the relative request URL, excluding the scheme and host. The query string may be included; the verifier compares the path component.

Canonically serialize the request body with recursively sorted keys and compact JSON separators. Use an empty object for a request without a body.

Hash that canonical body with SHA-256 and create a short-lived payload containing iat, exp, urlPath, userId, body, and a unique jti.

Base64url-encode the header and payload, then sign header.payload with P-256 and SHA-256.

Send the resulting bearer token with the same API-user key in the Api-Key header.

Generate a new token for every request. Changing the path, body keys, or body values after token generation invalidates the request binding.

Credential and key safety

Store credentials in a secret manager or protected server environment variables.
Do not log bearer tokens, API keys, private keys, or complete bank-account details.
Rotate credentials immediately if they may have been exposed.
Keep server time synchronized. Tokens expire 120 seconds after they are issued, so clock skew causes 401 errors.
Restrict source IPs where appropriate; see API user IP whitelisting.
Use the least-privileged API user required by the integration.

Authentication failures

HTTP status	Meaning	What to check
`401`	Authentication failed	Missing or expired token, wrong API key, mismatched path/body signature, or clock skew.
`403`	Authenticated but not permitted	API-user role, policy, vault permission, organization scope, sub-org scope, or IP allowlist.

Do not treat a 403 as a token-refresh problem. Verify authorization and resource scope before retrying.

Setup references

Use Setting up API User to provision credentials and API user IP whitelisting to restrict allowed source addresses.

API Basics

Approvals

Accounts

Sub-Orgs

Transactions

Base URL

Recommended: use the JavaScript SDK

Generate a bearer token manually

Required headers

How request signing works

Credential and key safety

Authentication failures

Setup references

​Base URL

​Recommended: use the JavaScript SDK

​Generate a bearer token manually

​Required headers

​How request signing works

​Credential and key safety

​Authentication failures

​Setup references

Base URL

Recommended: use the JavaScript SDK

Generate a bearer token manually

Required headers

How request signing works

Credential and key safety

Authentication failures

Setup references