Host names

The Cloud Vault API can be accessed on the following hostnames.

EnvironmentHost name


The Cloud Vault API uses Bearer (Token) Authentication to authenticate any request. These tokens are JSON Web Tokens (JWT) which need to be created server-side by your application.

curl -i -X GET "" \
    -H "authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"

The easiest way to generate these is with one of our SDKs.

Install a server-side SDK

Use the package manager in your preferred programming language to install our server-side SDK. Token generation can only be done server side and we do not recommend doing this client side as it will expose your API key to your customers.

npm install @gr4vy/node --save
# or: yarn add @gr4vy/node

Initialize the SDK client

Next, initialize the SDK with your private key.

const fs = require("fs");
const { Client } = require("@gr4vy/node");
// or: import { Client } from "@gr4vy/node";

const key = String(fs.readFileSync("./private_key.pem"));

const client = new Client({
  gr4vyId: "vault",
  privateKey: key,

The Gr4vy ID is the unique identifier for your instance. Together with the environment (sandbox or production) it is used to connect to the right APIs.

This assumes the key you created in the previous step is kept in a file called private_key.pem that is kept in the same folder next to the code. You could store this key in an environment variable or a secure vault.

Make an API call

To call the Cloud Vault API, you can either use our SDK directly or use the SDK to generate a JWT for use outside of the SDK.

Each SDK will automatically handle authentication for any server-to-server calls. Generating a token for use outside of the SDK can be useful in a micro-services architecture. In all other situations use the built-in SDK methods for making an API call.

// use the SDK to make an API call
const response = await this.newCheckoutSession();
// or get a token for use outside of the SDK
const token = client.getBearerToken([""]);
// next, use the token to make an API call

To learn more about our API authentication, and how to generate the JWT without our SDKs, please see our more extensive authentication guide.