Authentication

GoPayLocal supports multiple authentication methods depending on the endpoint and use case.

Public API (Banner + SDK)

Public endpoints (banner config, banner script) use public API keys passed as URL parameters or headers. No session or OAuth is required.

URL Parameter

GET https://api.gopaylocal.com/v1/banner/config/gpl_pk_live_abc123

Script Tag

<script src="https://api.gopaylocal.com/v1/banner/script.js?key=gpl_pk_live_abc123" async></script>

Public keys (prefix gpl_pk_) can only access read-only banner configuration endpoints. They are safe to use in client-side code.

Secret API Key

For server-side API access (creating products, managing campaigns, etc.), use secret API keys in the Authorization header:

curl

curl -X GET https://api.gopaylocal.com/v1/products \
  -H "Authorization: Bearer gpl_sk_live_xyz789" \
  -H "Content-Type: application/json"

JavaScript

const response = await fetch('https://api.gopaylocal.com/v1/products', {
  headers: {
    'Authorization': 'Bearer gpl_sk_live_xyz789',
    'Content-Type': 'application/json',
  },
});
const products = await response.json();

Danger

Secret keys (gpl_sk_*) must never be exposed in client-side code, public repositories, or frontend bundles.

Session Authentication (Dashboard)

The GoPayLocal dashboard uses Better Auth session cookies for authentication. This is not relevant for API integrations but is documented for completeness.

Login Flow

1. User visits app.gopaylocal.com/login
2. Better Auth creates a session cookie
3. All dashboard API calls include the session cookie automatically

OAuth Providers

The dashboard supports social login:

Provider	Sign In URL
Google	POST /api/auth/signin/google
GitHub	POST /api/auth/signin/github

Error Responses

401 Unauthorized

Returned when no valid authentication is provided:

{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden

Returned when the API key does not have permission for the requested operation:

{
  "error": "forbidden",
  "message": "Public keys cannot access this endpoint. Use a secret key."
}

Rate Limiting

API requests are rate-limited per API key:

Plan	Rate Limit
Free	100 requests/minute
Pro	500 requests/minute
Business	2,000 requests/minute

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1234567890

When rate-limited, you receive a 429 Too Many Requests response:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 30 seconds.",
  "retryAfter": 30
}