Authentication

The 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.

​

Authenticate an API call

Every API endpoint that requires authentication expects an authorization HTTP-header with a signed JWT token as its value (prefixed with bearer).

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

​

Create an API key

To sign a JWT you will need to create a new API key-pair in your dashboard.

To create a new API key visit the Integrations panel in your dashboard and click the Add API key button. You can store the API key with your code or store it in a secure environment accessible to your application.

​

Merchants access

When selecting an API key, if your instance has Multi Merchant enabled then you can select whether the API key can access All merchants or only one. We recommend you restrict an API key to only one merchant account when integrating into Embed, our SDKs, or our e-commerce platforms like Magento, Salesforce Commerce Cloud, and Commerce Tools.

​

Permissions

When selecting an API key, you can select whether to generate a key that has access to all APIs within the merchants it has access to (Full access) or only to APIs used for processing payments (Processing only). We recommend you use the Processing only for any API keys with our e-commerce platforms like Magento, Salesforce Commerce Cloud, and Commerce Tools.

​

Algorithm

Our API supports 2 algorithms for signing JWTs: ECDSA and RSA. We recommend you use ECDSA unless your environment does not support this stronger and newer algorithm. The RSA algorithm is available for those environments that do not support ECDSA. RSA keys provide considerably less security for the same key size and are currently not supported by our SDKs.

​

JWT using SDK

JWTs can be generated using one of our SDKs, or manually using a compatible JWT library. For your convenience we recommend using one of our SDKs as they make the process a lot easier.

First, install the SDK.

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

Then, initialize the client with your API key and generate the token.

const fs = require("fs");
const { Client } = require("@gr4vy/node");
const key = String(fs.readFileSync("./private.key"));

const client = new Client({
  gr4vyId: "example",
  privateKey: key,
});

const token = client.getBearerToken(["transactions.read"]);

​

Manual JWT

In some cases you might not want to use one of our SDKs, or an SDK in your language might not be available. In those cases you can construct, and sign the JWT with one of the many libraries available on jwt.io.

At the high level a JWT is build up out of 3 pieces:

• A header defining the algorithm and key used to create the JWT.
• A set of claims that define the token’s scope and other permissions.
• A cryptographic signature based on the header and the claims, signed using your private key.

Combine, these 3 pieces make up the JSON Web Token (JWT). See jwt.io for more details on the specification and available libraries for generating JWTs.

​

JWT header

The JWT header defines the type of encryption algorithm as well as the private key used to generate the signature.

{
  "typ": "JWT",
  "alg": "ES512", // OR RS512 depending on your key
  "kid": "d757c76acbd74b56"
}

​

JWT claims

The claims define when the token was created and what access it has.

{
  "iss": "My JWT Generation Tool",
  "nbf": 1607976645,
  "exp": 1607976314,
  "jti": "0fe1fb1b-2f7e-4c8d-b0eb-aae5d0ec98f7",
  "scopes": ["transactions.read"],
  "embed": {
    "amount": "200",
    "currency": "AUD",
    "buyer_id": "d757c76a-cbd7-4b56-95a3-40125b51b29c",
    "metadata": { "key": "value" },
    "cart_items": [
      {
        "name": "Joust Duffle Bag",
        "quantity": "1",
        "unit_amount": "9000",
        "tax_amount": "0"
      }
    ]
  }
}

​

Claims

The API supports the following JWT claims.

​

Scopes

The API supports the following values for the scopes claims.

The following resource names are recognized. Please see the reference documentation for more details as to what scope is required per endpoint.

• anti-fraud-services
• api-logs
• buyers
• buyers.billing-details
• card-scheme-definitions
• checkout-sessions
• connections
• digital-wallets
• flows
• payment-methods
• payment-method-definitions
• payment-options
• payment-service-definitions
• payment-services
• reports
• transactions

​

Signature & assembly

Finally, the JWT signature is generated by appending the Base64 encoded header and claims (separated with a .) and run it through the key’s algorithm.

ECDSASHA512(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  public_key,
  private_key
)

The assembled JWT is then formed by appending the Base64 encoded header, claims, and signature separated by a full stop.

base64UrlEncode(header) + "." + base64UrlEncode(payload) + "." + base64UrlEncode(signature)