Authentication

GovPayPlan supports multiple authentication methods depending on your integration type.

API Key Authentication

The simplest authentication method for server-to-server communication.

Obtaining API Keys

1. Log in to the Admin Portal as an administrator
2. Navigate to Settings > API
3. Click Generate New Key
4. Copy and securely store the key

DANGER

API keys provide full access to your account. Never expose them in client-side code, public repositories, or logs.

Using API Keys

Include the API key in the Authorization header:

curl -X GET https://api.govpayplan.com/v1/payments \
  -H "Authorization: Bearer gpp_live_abc123xyz"

Key Prefixes

Prefix	Environment
gpp_test_	Sandbox
gpp_live_	Production

Key Management

Rotating Keys

Regularly rotate API keys for security:

1. Generate a new key
2. Update your applications
3. Delete the old key

Revoking Keys

If a key is compromised:

1. Navigate to Settings > API
2. Find the compromised key
3. Click Revoke
4. Generate a new key

OAuth 2.0

For applications that act on behalf of users or need delegated access.

OAuth Flow

1. Authorization Request: Redirect user to GovPayPlan
2. User Authorization: User grants permission
3. Authorization Code: Receive code via callback
4. Token Exchange: Exchange code for access token
5. API Access: Use token for requests

Authorization URL

https://auth.govpayplan.com/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=payments:read payments:write

Token Exchange

curl -X POST https://auth.govpayplan.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTH_CODE",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "https://yourapp.com/callback"
  }'

Response

{
  "access_token": "gpp_oauth_abc123",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "gpp_refresh_xyz789",
  "scope": "payments:read payments:write"
}

Using OAuth Tokens

curl -X GET https://api.govpayplan.com/v1/payments \
  -H "Authorization: Bearer gpp_oauth_abc123"

Refreshing Tokens

curl -X POST https://auth.govpayplan.com/oauth/token \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "gpp_refresh_xyz789",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

Scopes

Control access level with OAuth scopes:

Scope	Description
payments:read	Read payment information
payments:write	Create and modify payments
refunds:write	Issue refunds
reports:read	Access reports
users:read	Read user information
users:write	Manage users

Publishable Keys

For client-side integrations (embedded forms), use publishable keys.

Characteristics

• Safe to expose in client-side code
• Limited permissions (only initialize payments)
• Cannot read sensitive data

Usage

const gpp = GovPayPlan.init({
  publishableKey: 'gpp_pub_abc123'
});

Security Best Practices

Do

• Store keys in environment variables
• Use different keys for sandbox/production
• Rotate keys regularly
• Monitor key usage
• Use minimum necessary scopes

Don't

• Commit keys to version control
• Log API keys
• Share keys via email or chat
• Use production keys in development
• Grant excessive scopes

Troubleshooting

Common Errors

Error	Cause	Solution
401 Unauthorized	Invalid/missing key	Verify API key
403 Forbidden	Insufficient permissions	Check key scopes
Key expired	OAuth token expired	Refresh the token

Testing Authentication

# Test your API key
curl -X GET https://sandbox-api.govpayplan.com/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

Related Topics

• Getting Started - Initial setup
• Security Settings - Manage API access