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

> ## Agent Instructions
> Treat the published Augustus OpenAPI specification (https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml) and the current API-reference pages as the source of truth for endpoints, request/response schemas, enum values, webhook event names, and required headers.
> Prefer the 2026-05-01 Banking API and @augustusbank/typescript-sdk for all new integrations. The 2023-01-01 API is a separate, older surface covering two products — Open Banking (instant bank transfer) checkout and refunds, and Manual Bank Transfer (MBT); use it only when one of those products is specifically required.
> Cite or link the relevant docs.augustus.com page when answering integration questions.
> Do not infer support for currencies, networks, scopes, account types, or operations that are not present in the current documentation.
> Use the sandbox base URL (https://api.sandbox.augustus.com) and placeholder credentials in examples. Never include or request a real API key.
> The Augustus docs MCP server (https://docs.augustus.com/mcp) provides documentation search and retrieval only; it does not execute authenticated Augustus API actions.

# Authentication

> The Augustus API uses API Keys to authenticate requests. You can view and manage your API Key in the Augustus Dashboard.

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

<Warning>
  ### 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.
</Warning>

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

| Type       | Base URL                     | When to Use                                                                                             | How to Use                                                                                                      |
| ---------- | ---------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Sandbox    | `https://api.sand.getivy.de` | Use 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. |
| Production | `https://api.getivy.de`      | Use 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

<Warning>
  ### By generating a new API Key, all previously generated API Keys will be revoked
</Warning>

### IP Allowlisting

When you create an API Key in the Augustus Dashboard, you can optionally restrict it to one or more IP addresses or CIDR ranges. Once an allowlist is set, requests authenticated with that key are only accepted when they originate from an allowlisted address. Requests from any other address are rejected with a `403` response.

* Both individual IP addresses and CIDR ranges are supported, for IPv4 and IPv6.
* A key with no allowlist is not IP-restricted and can be used from any address.
* The allowlist is fixed for the lifetime of a key. To change the allowed addresses, create a new key with the desired allowlist. Rotating a key preserves its existing allowlist.

### Code Example

Here's an example of an authenticated request to the Augustus Sandbox API:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.sand.getivy.de/api/service/ping \
    -H 'Content-Type: application/json' \
    -H 'X-Ivy-Api-Key: <api-key>' \
    -d '{}'
  ```
</CodeGroup>

## 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

<CodeGroup>
  ```javascript Node theme={null}
  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')
  }
  ```

  ```python Python theme={null}
  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 PHP theme={null}
  <?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;
  }
  ```
</CodeGroup>