API Key Authentication

Overview

Unter uses API key authentication to secure merchant API endpoints. Each API key is associated with a specific merchant account and can be configured with different permissions and rate limits.

API Key Format

All Unter API keys follow this format:

unter_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• Keys always start with the prefix unter_

• Followed by 40 random characters

• Total length: 46 characters

Authentication Methods

You can authenticate API requests using either of these methods:

1. X-API-Key Header (Recommended)

Include your API key in the X-API-Key header:

curl -H "X-API-Key: unter_YOUR_API_KEY_HERE" \
  https://api.unter.tech/api/payment-requests

2. Authorization Header

Alternatively, you can use the Authorization header as a Bearer token:

curl -H "Authorization: Bearer unter_YOUR_API_KEY_HERE" \
  https://api.unter.tech/api/payment-requests

Security Features

Key Hashing and Security

When an API key is generated, you'll see the full key (e.g., unter_abc123...) displayed once in your dashboard. This is the only time you'll be able to see the complete key, so make sure to copy and store it securely.

Error Responses

Missing API Key

{
  "error": "API key required",
  "message": "Please provide an API key via X-API-Key header or Authorization header"
}

Status Code: 401 Unauthorized

Invalid API Key

{
  "error": "Invalid API key",
  "message": "The provided API key is invalid or expired"
}

Status Code: 401 Unauthorized

Suspended Account

{
  "error": "Account suspended",
  "message": "Your merchant account has been suspended"
}

Status Code: 403 Forbidden

Environments

API keys can be created for different environments:

• production - For live payment processing (default)

• sandbox - For testing and development

Make sure to use the appropriate key for your environment.

Code Examples

JavaScript (Node.js)

const axios = require('axios');

const apiKey = process.env.UNTER_API_KEY;

const client = axios.create({
  baseURL: 'https://api.unter.tech/api',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json'
  }
});

// Create a payment request
async function createPaymentRequest(data) {
  try {
    const response = await client.post('/payment-requests', data);
    return response.data;
  } catch (error) {
    if (error.response?.status === 401) {
      console.error('Authentication failed:', error.response.data.message);
    }
    throw error;
  }
}