Skip to main content
Open Wearables provides two authentication methods to secure API access:

JWT Tokens

Session-based authentication for dashboard and developer portal access

API Keys

Long-lived credentials for server-to-server API integration

​
Authentication Methods

​
JWT Tokens (Developer Portal)

JSON Web Tokens are used for authenticating developers accessing the dashboard and developer portal. JWTs are short-lived (configurable expiration) and include refresh token support. Use JWT tokens when:
  • Building web applications with user sessions
  • Accessing developer account management endpoints
  • Managing API keys through the dashboard
  • Short-lived access with automatic refresh is preferred

​
API Keys (Server Integration)

API keys are long-lived credentials designed for server-to-server communication. They provide programmatic access to the API without requiring user sessions. Use API keys when:
  • Integrating Open Wearables into your backend services
  • Building automated scripts or data pipelines
  • Accessing wearable data on behalf of your users
  • Long-lived credentials are acceptable

​
Authentication Flow Comparison

​
Quick Start Examples

# 1. Login and get access token
curl -X POST https://api.openwearables.com/api/v1/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "[email protected]" \
  -d "password=your-password"

# Response:
# {
#   "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
#   "token_type": "bearer",
#   "refresh_token": "a1b2c3d4e5f6...",
#   "expires_in": 3600
# }

# 2. Use the access token
curl https://api.openwearables.com/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Security Best Practices

  • Never commit API keys or tokens to version control
  • Use environment variables or secret management systems
  • Rotate API keys periodically
  • Delete unused API keys immediately
  • All API requests must use HTTPS
  • Never send authentication credentials over HTTP
  • Validate SSL certificates in production
  • Store refresh tokens securely (httpOnly cookies recommended)
  • Implement automatic token refresh before expiration
  • Handle 401 errors gracefully by refreshing tokens
  • Log out users when refresh tokens expire
  • Track which services use which API keys
  • Set up alerts for unusual activity
  • Use different API keys for different environments
  • Rotate keys immediately if compromised

​
Error Handling

Both authentication methods return standard HTTP status codes:
Status CodeDescriptionAction
200SuccessContinue with response data
401UnauthorizedInvalid credentials or expired token - re-authenticate
403ForbiddenValid auth but insufficient permissions
422Validation ErrorCheck request body format
429Rate LimitedReduce request frequency
500Server ErrorRetry with exponential backoff
Avoid common mistakes:
  • Don’t expose API keys in client-side code
  • Don’t use JWT tokens for long-running server processes
  • Don’t ignore token expiration - implement refresh logic
  • Don’t reuse the same API key across all environments

​
Next Steps

JWT Token Authentication

Learn about login, token refresh, and session management

API Key Management

Create, rotate, and manage API keys for your integrations

Build docs developers (and LLMs) love

Get started for freeTalk to us