# Authentication
Learn how to manage API keys and authenticate with the ZenPays API.
## API Key Types
ZenPays uses two types of API keys:
| Key Type | Prefix | Usage |
|----------|--------|-------|
| **Live** | `zp_live_` | Production payments |
| **Test** | `zp_test_` | Sandbox testing |
## Getting Your API Key
1. Log in to your [ZenPays Dashboard](https://dashboard.zenpays.com)
2. Navigate to **Settings** → **API Keys**
3. Copy your API key
:::warning
Keep your API keys secure. Never expose them in client-side code or commit them to version control.
:::
## Using the SDK
```typescript
import { ZenPays } from '@zenxdigitalholdings/zenpays'
const zenpays = new ZenPays({
apiKey: process.env.ZENPAYS_API_KEY!,
})
```
```python
import os
from zenpays import ZenPays
zenpays = ZenPays(api_key=os.environ["ZENPAYS_API_KEY"])
```
## Environment-Based Authentication
```typescript
// Determine environment from API key prefix
function getEnvironment(apiKey: string): 'live' | 'test' {
return apiKey.startsWith('zp_live_') ? 'live' : 'test'
}
const zenpays = new ZenPays({
apiKey: process.env.ZENPAYS_API_KEY!,
})
console.log('Environment:', getEnvironment(process.env.ZENPAYS_API_KEY!))
```
```python
import os
# Determine environment from API key prefix
def get_environment(api_key: str) -> str:
if api_key.startswith("zp_live_"):
return "live"
elif api_key.startswith("zp_test_"):
return "test"
return "dev"
zenpays = ZenPays(api_key=os.environ["ZENPAYS_API_KEY"])
print(f"Environment: {get_environment(os.environ['ZENPAYS_API_KEY'])}")
```
## IP Whitelisting
For enhanced security, whitelist IPs allowed to use your API keys:
```typescript
// List whitelisted IPs
const ips = await zenpays.merchants.listWhitelistedIPs()
// Add a new IP
await zenpays.merchants.addIPToWhitelist(
'203.0.113.50',
'Production Server'
)
// Remove an IP
await zenpays.merchants.removeIPFromWhitelist('ip_entry_id')
```
```python
# List whitelisted IPs
ips = zenpays.merchants.list_whitelisted_ips()
# Add a new IP
zenpays.merchants.add_ip_to_whitelist(
"203.0.113.50",
"Production Server"
)
# Remove an IP
zenpays.merchants.remove_ip_from_whitelist("ip_entry_id")
```
## Two-Factor Authentication
Enable 2FA for additional security:
```typescript
// Setup 2FA
const setup = await zenpays.security.setup2FA()
console.log('Scan this QR code:', setup.qrCodeUrl)
console.log('Backup codes:', setup.backupCodes)
// Verify 2FA code
await zenpays.security.verify2FA({ code: '123456' })
// Check 2FA status
const status = await zenpays.security.is2FAEnabled()
console.log('2FA enabled:', status.enabled)
```
```python
# Setup 2FA
setup = zenpays.security.setup_two_factor()
print(f"Scan this QR code: {setup['qr_code_url']}")
print(f"Backup codes: {setup['backup_codes']}")
# Verify 2FA code
zenpays.security.verify_two_factor({"code": "123456"})
# Check 2FA status
status = zenpays.security.is_two_factor_enabled()
print(f"2FA enabled: {status['enabled']}")
```
## Best Practices
1. **Use environment variables** - Never hardcode API keys
2. **Rotate keys regularly** - Create new keys and revoke old ones
3. **Use minimal scopes** - Only grant necessary permissions
4. **Enable IP whitelisting** - Restrict access to known IPs
5. **Enable 2FA** - Add an extra layer of security
6. **Monitor usage** - Check API key usage in the dashboard
## Handling Authentication Errors
```typescript
import { AuthenticationError, AuthorizationError } from '@zenxdigitalholdings/zenpays'
try {
await zenpays.payments.createPaymentIntent({
amount: 1000,
currency: 'USD',
})
}
catch (error) {
if (error instanceof AuthenticationError) {
console.error('Invalid API key')
}
else if (error instanceof AuthorizationError) {
console.error('API key lacks required permissions')
}
}
```
```python
from zenpays.errors import AuthenticationError, PermissionError
try:
zenpays.payments.create_payment_intent({
"amount": 1000,
"currency": "USD",
})
except AuthenticationError:
print("Invalid API key")
except PermissionError:
print("API key lacks required permissions")
```
## Next Steps
- [Quick Start](/docs/getting-started/quick-start) - Create your first payment
- [Security Guide](/docs/guides/security) - Learn more about security best practices
- [Webhooks](/docs/guides/webhooks) - Verify webhook signatures