Authentication

Learn how to authenticate your requests to the SpatialFlow API using API keys or JWT tokens.

Authentication Methods

SpatialFlow supports two authentication methods:

1. API Keys - Simple and fast, perfect for server-side applications and programmatic access
2. JWT Tokens - Temporary tokens with expiration, ideal for user sessions

API Keys

API keys are the simplest way to authenticate. They're long-lived credentials that don't expire.

Creating an API Key

1. Log in to your Dashboard
2. Go to Settings → API Keys
3. Click Generate New API Key
4. Name your key and set permissions
5. Copy the key (you won't see it again!)

Using API Keys

Include your API key in the Authorization header:

curl https://api.spatialflow.io/api/v1/geofences \
  -H "Authorization: Bearer your-api-key-here"

Keep Your API Keys Secret

Never commit API keys to version control or share them publicly. Use environment variables or secret management services.

JWT Tokens

JWT (JSON Web Tokens) are temporary credentials that expire after a set time period.

Getting a JWT Token

curl -X POST https://api.spatialflow.io/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Using JWT Tokens

curl https://api.spatialflow.io/api/v1/geofences \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Refreshing Tokens

Access tokens expire after 24 hours by default (configurable by workspace admins). Use the refresh token to get a new access token:

curl -X POST https://api.spatialflow.io/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "your-refresh-token-here"
  }'

Best Practices

Security

• ✅ Use environment variables for credentials
• ✅ Rotate API keys regularly
• ✅ Use JWT tokens for user-facing applications
• ✅ Implement token refresh logic
• ❌ Never hardcode credentials in source code
• ❌ Don't share API keys between environments

Performance

• Cache JWT tokens until expiration
• Reuse connections when making multiple requests
• Implement exponential backoff for failed authentication attempts

Rate Limiting

Authentication endpoints have the following rate limits:

• Login: 5 requests per minute per IP address
• Refresh: 10 requests per minute per user

For API request rate limits by subscription tier, see Rate Limiting. When limits are exceeded, the API returns a 429 Too Many Requests status code with a Retry-After header indicating when to retry.

Error Handling

Common Authentication Errors

Status Code	Error	Solution
401	Invalid credentials	Check your API key or token
401	Token expired	Refresh your JWT token
403	Insufficient permissions	Check your API key scopes
429	Rate limit exceeded	Implement exponential backoff

Example Error Response

{
  "detail": "Invalid or expired token"
}

Next Steps

• Create your first geofence - Start building
• API Reference - Explore all endpoints
• Best Practices - Production-ready patterns