Authentication

Overview

Hedge Payments uses API keys and JWT tokens to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure and never share them in publicly accessible areas.

API Keys

API keys are the primary method of authentication for Hedge Payments. You can find your API keys in the Dashboard under Settings → API Keys.

Types of API Keys

Using API Keys

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

curl -X POST https://api.hedgepayments.com/api/payments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "currency": "USD",
    "customerEmail": "user@example.com"
  }'

JWT Tokens

For added security in client-side applications, you can generate short-lived JWT tokens from your server using your API key. These tokens can be safely used in frontend code.

Generating a JWT Token

const token = await hedge.auth.createToken({
  expiresIn: '1h', // Token expires in 1 hour
  scope: ['payments:read', 'payments:create']
})

// Send token to client
res.json({ token: token.jwt })

token = hedge.auth.create_token(
    expires_in='1h',  # Token expires in 1 hour
    scope=['payments:read', 'payments:create']
)

# Send token to client
return {'token': token.jwt}

Using JWT Tokens

Use JWT tokens the same way as API keys, in the Authorization header:

// Client-side code (safe to use)
const response = await fetch('https://api.hedgepayments.com/api/payments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${jwtToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 100.00,
    currency: 'USD',
    customerEmail: 'user@example.com'
  })
})

Scopes and Permissions

Control access to your API resources using scopes. Each scope grants specific permissions:

Security Best Practices

• 🔒 Use environment variables:
  Store API keys in environment variables, never hard-code them in your application.
• ⏱️ Set appropriate expiration times:
  JWT tokens should have short expiration times (1-24 hours) to minimize security risks.
• 🎯 Use minimal scopes:
  Only grant the permissions necessary for each token's intended use.
• 🔄 Rotate keys regularly:
  Periodically regenerate your API keys, especially if you suspect they may have been compromised.
• 🚫 Never expose keys client-side:
  API keys should only be used on your backend servers. Use JWT tokens for client-side operations.

Error Handling

When authentication fails, Hedge Payments returns a 401 Unauthorized status code:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key",
    "type": "authentication_error"
  }
}

Common authentication errors:

• invalid_api_key - The provided API key is invalid
• expired_token - The JWT token has expired
• insufficient_permissions - The token doesn't have the required scope
• missing_authorization - No Authorization header was provided