Authentication

Overview

The goBlink API uses Bearer token authentication. Every request must include your API key in the Authorization header. API keys are scoped to a single merchant account and carry full permissions for that account's resources.

Authorization: Bearer gb_live_your_api_key_here

API Key Types

goBlink issues two types of API keys for each merchant account:

Both key types authenticate against the same base URL (https://merchant.goblink.io/api/v1). The API automatically routes requests to the appropriate environment based on the key prefix.

Test Keys

Test keys provide a sandboxed environment where you can:

• Create payments that settle instantly without real blockchain transactions
• Trigger specific outcomes using special test amounts
• Test webhook delivery with real HTTP requests
• Validate your integration end-to-end before going live

Live Keys

Live keys process real transactions on public blockchains. Treat these keys with the same level of care as any production secret.

Making Authenticated Requests

Include your API key in the Authorization header of every request:

cURL

curl https://merchant.goblink.io/api/v1/payments \
  -H "Authorization: Bearer gb_test_sk_a1b2c3d4e5f6g7h8i9j0"

Node.js

const response = await fetch("https://merchant.goblink.io/api/v1/payments", {
  headers: {
    "Authorization": `Bearer ${process.env.GOBLINK_API_KEY}`,
    "Content-Type": "application/json",
  },
});

Python

import requests
import os
 
response = requests.get(
    "https://merchant.goblink.io/api/v1/payments",
    headers={
        "Authorization": f"Bearer {os.environ['GOBLINK_API_KEY']}",
        "Content-Type": "application/json",
    },
)

Authentication Errors

If authentication fails, the API returns a 401 Unauthorized response:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key.",
    "status": 401
  }
}

Common causes of authentication errors:

Generating API Keys

To create or manage API keys:

1. Log in to the goBlink Dashboard.
2. Navigate to Settings > API Keys.
3. Click Generate New Key.
4. Give the key a descriptive label (e.g., "Production Backend", "Staging Server").
5. Copy the key immediately -- it will not be shown again after creation.

You can have up to 5 active keys per environment (test and live). This allows you to use separate keys for different services or deploy key rotation without downtime.

Key Rotation

To rotate an API key without interrupting service:

1. Generate a new key in the dashboard.
2. Update your application configuration to use the new key.
3. Deploy the change.
4. Verify that requests succeed with the new key.
5. Revoke the old key in the dashboard.

goBlink supports multiple active keys simultaneously, so both old and new keys work during the transition window. There is no expiration on keys -- they remain active until manually revoked.

Automated Key Rotation Example

// If you store keys in environment variables, rotate by deploying
// with the new key value. No code changes required.
 
// .env (before rotation)
// GOBLINK_API_KEY=gb_live_old_key_abc123
 
// .env (after rotation)
// GOBLINK_API_KEY=gb_live_new_key_def456
 
const client = new GoBlink({
  apiKey: process.env.GOBLINK_API_KEY,
});

Webhook Signature Verification

Webhook payloads are signed separately from API key authentication. Each webhook endpoint has its own signing secret, used to compute an HMAC-SHA256 signature. See the Webhooks documentation for details on verifying signatures.

Security Best Practices

Store Keys Securely

Never hardcode API keys in your source code. Use environment variables or a secrets manager:

# Environment variable
export GOBLINK_API_KEY="gb_live_your_api_key_here"

// Read from environment
const apiKey = process.env.GOBLINK_API_KEY;

Restrict Access

• Only backend services should use API keys. Never expose keys in client-side JavaScript, mobile apps, or public repositories.
• Use the Embeddable Button or Checkout URL for client-side payment flows -- these do not require your API key.

Monitor Key Usage

The goBlink Dashboard provides an API activity log under Settings > API Keys > Activity. Review this log regularly to detect unauthorized usage. Each log entry includes:

• Timestamp
• Endpoint called
• HTTP method and status code
• IP address of the caller
• API key label used

IP Allowlisting

For additional security, you can restrict API key usage to specific IP addresses:

1. Go to Settings > API Keys in the dashboard.
2. Click the key you want to restrict.
3. Under IP Allowlist, add the IP addresses or CIDR ranges that should be permitted.
4. Save changes.

When an allowlist is configured, requests from non-listed IPs receive a 403 Forbidden response:

{
  "success": false,
  "error": {
    "code": "IP_NOT_ALLOWED",
    "message": "Request IP address is not in the allowlist for this API key.",
    "status": 403
  }
}

Rate Limiting

Requests are rate-limited per API key:

When you exceed the rate limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry after 12 seconds.",
    "status": 429
  }
}

Rate limit headers are included in every response:

Handling Rate Limits

Implement exponential backoff in your client:

async function apiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);
 
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get("Retry-After") || "5");
      const delay = retryAfter * 1000 * Math.pow(2, attempt);
      console.warn(`Rate limited. Retrying in ${delay}ms...`);
      await new Promise((resolve) => setTimeout(resolve, delay));
      continue;
    }
 
    return response;
  }
 
  throw new Error("Max retries exceeded");
}