Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.augustus.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Augustus API uses API Keys to authenticate requests. You can view and manage your API Key in the Augustus Dashboard. To request access to the Augustus Dashboard, please contact 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

Augustus authenticates your API requests using your account’s API Key. To authenticate each request to the Augustus API, set your API Key in the X-Ivy-Api-Key header. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. Augustus returns an authentication error 401 if the key is incorrect or outdated. You can use the Augustus Dashboard to rotate your API Key. If you’re setting up Augustus through a Third-Party Platform (3PP), copy and paste your API Key in live mode to begin processing payments.

​
Sandbox and Production Modes

All Augustus API requests occur in either Sandbox or Production Mode. API objects in one mode aren’t accessible in the other. For instance, a Sandbox User object cannot be part of a Production-Mode Checkout Session.
TypeBase URLWhen to UseHow to Use
Sandboxhttps://api.sand.getivy.deUse this mode as you build your app. In Sandbox Mode, payments will not be processed.Integrate Augustus as you would in Production Mode. You will automatically be redirected to test payment flows.
Productionhttps://api.getivy.deUse this mode when you’re ready to launch the checkout. In Production Mode, payments will be processed.Use valid bank accounts. Use actual payment authorizations and payment flows.

​
Generate a New API Key

  1. Go to your Augustus Dashboard
  2. Click on the Generate API Key button

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

​
Code Example

Here’s an example of an authenticated request to the Augustus Sandbox API: 
curl https://api.sand.getivy.de/api/service/ping \
  -H 'Content-Type: application/json' \
  -H 'X-Ivy-Api-Key: <api-key>' \
  -d '{}'

​
Webhooks

Augustus may send requests to endpoints that you set up, for example, as Webhooks.

​
Security & Signature

All requests sent to your endpoints will include the X-Ivy-Signature header. Verify this value to ensure the request is coming from Augustus and not from a third party. To validate incoming requests:
  • Obtain the Webhook Signing Secret from the Augustus Dashboard
  • Check the X-Ivy-Signature Header against a newly calculated Signature for every incoming request
  • Calculate the signature using the request body and the Webhook Signing Secret with 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')
}