Authentication

Overview

The Ivy API uses API keys to authenticate requests. You can view and manage your API key in the Ivy Dashboard. You can request access to the Ivy Dashboard by contacting our support team.

🚧

Your API key carries many privileges, so be sure to keep it secure!

Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

API Keys

Ivy authenticates your API requests using your account’s API key. Use your API key by setting it in the X-Ivy-Api-Key header of each request to the Ivy API.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. Ivy raises an authentication error 401 if the key is incorrect or outdated.

You can use the Ivy Dashboard to roll the API key. If you’re setting up Ivy through a third party platform (3PP), copy and paste your API key in live mode to begin processing payments.

Sandbox and Production modes

All Ivy API requests occur in either sandbox or production mode. API objects in one mode aren’t accessible to the other. For instance, a Sandbox User object can’t be part of a Production-Mode CheckoutSession.

Generate a new API key

1. Go to the your Ivy Dashboard
2. Click on the Generate API key button

🚧

By generating a new API Key, all formerly generated API Keys will be revoked

Code Example

An authenticated request to the Ivy Sandbox API would for example look like below:

curl https://api.sand.getivy.de/api/service/ping \
    -H 'Content-Type: application/json'
    -H 'X-IVY-API-KEY: <api-key>'
    -d '{}'

Webhooks

Ivy may send requests to endpoints set up by you, e.g. as webhooks.

Security & Signature

All requests which are sent to any of your endpoints will include the X-Ivy-Signature header. Make sure to check the value to ensure that the request is coming from Ivy and not from a third party.

• Obtain the Webhook Signing Secret from the Ivy Dashboard
• For every incoming request you should check the X-Ivy-Signature Header against a newly calculated Signature
• The calculation is done with the request body and the Webhook Signing Secret using the HMAC & SHA-256 Hash

Code Examples

const { createHmac } = require('crypto')
const config = require('../config')

/*
  This middleware validates the request body against the X-Ivy-Signature header
  If the signature is invalid, an error is thrown
  If the signature is valid, the next middleware is called
*/
function validateRequest(req, res, next) {

  const secret = config.IVY_WEBHOOK_SIGNING_SECRET
  const data = req.body
  const expectedSignature = sign(data, secret)

  const signature = req.get('X-Ivy-Signature')

  if (signature !== expectedSignature) throw new Error('invalid signature!')

  next()
}

/*
  Parameter "data" is the request / response body
  The response is the X-IVY-SIGNATURE
*/
function sign(data, secret) {
  const hmac = createHmac('sha256', secret)
  hmac.update(JSON.stringify(data))
  return hmac.digest('hex')
}

import hmac
import hashlib
import json
import os

def sign(data):
    return hmac.new(
        os.environ['IVY_WEBHOOK_SIGNING_SECRET'].encode('utf-8'),
        json.dumps(data).encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

<?php
// Assuming you have a similar config file in PHP
require_once('../config.php');

/*
  This function validates the request body against the X-Ivy-Signature header.
  If the signature is invalid, false is returned.
*/
function isValidRequest(RequestInterface $request)
    {
  $hash = hash_hmac(
    'sha256',
    $request->getContent(),
    $this->config->getWebhookSecret());

  if ($request->getHeaders('x-ivy-signature')->getFieldValue() === $hash) {
    return true;
  }

  return false;
}