The API uses Bearer (Token) Authentication to authenticate requests. The value of this bearer token is a JSON Web Token (JWT), which is passed in the Authorization HTTP header and signed by your private API Key.

curl -X GET https://api.example.gr4vy.app/transactions \
  -H "authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIi..."

​
Create a new API key

To use the API you will need to generate a new API key. Head over to your dashboard and visit the Integrations page.

API key dashboard

On this page, click the Add API key button and select a name for your key. The name is purely for you to track what key is for what integration. You will need to store the downloaded key securely as we will not store this key for you.

Using an SDK is the most simple way to call and authenticate with our API. When using one of our SDKs to call the API, authentication is handled by the SDK client. You will only need to initialize the SDK with your private to handle authentication.

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

Please install the latest release of your preferred SDK.

Initialize the SDK client

Next, initialize the SDK with the ID of your instance and the 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: "[GR4VY_ID]",
  privateKey: key,
  environment: "sandbox",
});

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.

​
Summary

In this step you:

  • Learned about API authentication
  • Created a new private key for the API
  • Used an SDK to authenticate or manually created a token

Was this page helpful?

Introduction2. Get payment options