Authentication

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

Authentication Methods

SpatialFlow supports five authentication methods. Pick the one that fits your client.

Method	Best for	Notes
Email + password (JWT)	Browser sessions and first-time logins from a user-facing app	Issues a short-lived access token (4 h default) plus a refresh token. Detailed below under JWT Tokens.
API Keys	Server-to-server integrations, scripts, CI, backend services	Long-lived bearer tokens with scoped permissions. Detailed below under API Keys.
Google SSO	OAuth sign-in for web and mobile	Configure via SpatialFlow on AWS — see Google OAuth setup.
Apple Sign-In	iOS / iPadOS sign-in (required for App Store distribution)	Native Sign In with Apple via OAuth — see Apple Sign-In setup.
SAML SSO	Enterprise single sign-on (Okta, Azure AD, OneLogin, etc.)	Workspace admins configure an IdP and SpatialFlow's SP metadata. Available on Business and Enterprise plans — see SAML 2.0 setup.

The first two methods (JWT and API Keys) are the most common and are documented in full below. Google SSO, Apple Sign-In, and SAML SSO are administrator-configured at the workspace or deployment level; the linked sections cover the IdP / OAuth provider setup. Once configured, end users sign in through their IdP and the SpatialFlow API issues the same JWT pair documented under JWT Tokens.

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 X-API-KEY header:

curl https://api.spatialflow.io/api/v1/geofences/ \
  -H "X-API-KEY: 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": 14400,
  "token_type": "Bearer"
}

Using JWT Tokens

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

Refreshing Tokens

Access tokens expire after 4 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: 60 requests per minute per IP address, 15 requests per minute per email address
• Refresh: 30 requests per minute per token, 100 requests per minute per IP address

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