Authentication Guide
Learn how to authenticate with the Preswald API and secure your applications.
Table of Contents
API Keys
API keys are the simplest way to authenticate with the Preswald API. They provide full access to your account.
Security Warning
Keep your API keys secure and never expose them in client-side code.
Getting Your API Key
- Log in to your Preswald dashboard
- Navigate to Settings → API Keys
- Click "Generate New API Key"
- Copy and store your key securely
Using API Keys
# Using curl
curl -H "Authorization: Bearer your-api-key-here" \
https://api.preswald.com/v1/apps
# Using Python
import requests
headers = {
'Authorization': 'Bearer your-api-key-here',
'Content-Type': 'application/json'
}
response = requests.get(
'https://api.preswald.com/v1/apps',
headers=headers
)OAuth 2.0
OAuth 2.0 is recommended for applications that need to access user data on behalf of other users.
Authorization Code Flow
# Step 1: Redirect user to authorization URL
https://auth.preswald.com/oauth/authorize?
client_id=your-client-id&
redirect_uri=https://yourapp.com/callback&
response_type=code&
scope=read:apps write:apps&
state=random-state-string
# Step 2: Exchange code for access token
POST https://auth.preswald.com/oauth/token
Content-Type: application/json
{
"grant_type": "authorization_code",
"client_id": "your-client-id",
"client_secret": "your-client-secret",
"code": "authorization-code-from-step-1",
"redirect_uri": "https://yourapp.com/callback"
}JWT Tokens
JWT tokens are returned by the OAuth flow and can be used to authenticate API requests.
# Using JWT token
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
https://api.preswald.com/v1/apps
# Token refresh
POST https://auth.preswald.com/oauth/token
Content-Type: application/json
{
"grant_type": "refresh_token",
"refresh_token": "your-refresh-token"
}Scopes
Scopes define what permissions your application has when accessing the API.
| Scope | Description |
|---|---|
| read:apps | Read access to apps |
| write:apps | Create and modify apps |
| delete:apps | Delete apps |
| read:data | Access data sources |
| admin | Full account access |
Best Practices
- Use environment variables to store API keys and secrets
- Implement token refresh logic for OAuth applications
- Use the minimum required scopes for your application
- Rotate API keys regularly
- Monitor API usage and set up alerts for unusual activity
- Use HTTPS for all API requests
- Implement proper error handling for authentication failures
Troubleshooting
401 Unauthorized
Common causes:
- Invalid or expired API key
- Missing Authorization header
- Incorrect token format
403 Forbidden
Common causes:
- Insufficient permissions (scopes)
- Account suspended or limited
- Rate limit exceeded
Token Refresh Issues
Common causes:
- Expired refresh token
- Invalid client credentials
- Revoked application access