Authentication

Overview

Strike Auth Service uses JWT (JSON Web Tokens) for authentication, providing a secure and stateless way to authenticate users. The service supports multiple authentication methods and follows OAuth 2.0 standards where applicable.

Authentication Flow

User Registration/Login

Users can register or login using various methods (email/password, magic links, OAuth, etc.)

Token Issuance

Upon successful authentication, the service issues an access token and refresh token

API Requests

Include the access token in the Authorization header for authenticated requests

Token Refresh

Use the refresh token to obtain new access tokens when they expire

Token Types

Access Token

Purpose: Authenticate API requests
Lifetime: 1 hour (3600 seconds)
Format: JWT with user claims
Usage: Include in Authorization: Bearer <token> header

Refresh Token

Purpose: Obtain new access tokens
Lifetime: 30 days (configurable)
Format: Opaque string
Usage: Send to /token endpoint with grant_type=refresh_token

Service Role Key

Purpose: Admin operations and server-to-server communication
Lifetime: No expiration (until rotated)
Format: Opaque string
Usage: Include in Authorization: Bearer <service-role-key> header

Authentication Methods

Email & Password
Magic Links
OTP (SMS)
OAuth
Admin Login

Traditional authentication with email and password.

curl -X POST "http://localhost:8080/token?grant_type=password" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123"
  }'

Passwordless authentication via email links.

# Send magic link
curl -X POST "http://localhost:8080/magiclink" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "create_user": true
  }'

One-time password authentication via SMS.

# Send OTP
curl -X POST "http://localhost:8080/otp" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+1234567890",
    "create_user": true
  }'

Third-party provider authentication.

# Initiate OAuth flow
curl -X GET "http://localhost:8080/authorize?provider=google&redirect_to=https://yourapp.com/callback"

Enhanced authentication for administrators with privilege verification.

# Admin login with automatic privilege check
curl -X POST "http://localhost:8080/login-admin" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "securepassword123"
  }'

The admin login endpoint performs two-step verification: standard authentication followed by admin privilege validation via database lookup.

Security Headers

All authenticated requests should include the access token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Rate Limiting

Authentication endpoints include rate limiting to prevent abuse:

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Remaining requests in current window
`X-RateLimit-Reset`	Time until window resets (seconds)

Error Handling

Authentication errors follow a consistent format:

{
  "code": 401,
  "msg": "Invalid credentials",
  "details": "Email or password is incorrect"
}

Common authentication error codes:

Code	Description
`400`	Bad Request - Invalid request format
`401`	Unauthorized - Invalid or missing credentials
`403`	Forbidden - Insufficient permissions
`429`	Too Many Requests - Rate limit exceeded

JWT Token Structure

Access tokens are JWTs containing user information:

{
  "aud": "authenticated",
  "exp": 1640995200,
  "iat": 1640908800,
  "iss": "https://your-project.supabase.co/auth/v1",
  "sub": "123e4567-e89b-12d3-a456-426614174000",
  "email": "user@example.com",
  "phone": "+1234567890",
  "app_metadata": {
    "provider": "email",
    "providers": ["email"]
  },
  "user_metadata": {},
  "role": "authenticated"
}

Best Practices

Token Storage

Store access tokens in memory or secure storage
Store refresh tokens in secure, httpOnly cookies when possible
Never store tokens in localStorage in production

Token Refresh

Implement automatic token refresh before expiration - Handle refresh token rotation properly - Implement proper error handling for expired refresh tokens

Security

Always use HTTPS in production - Implement proper CORS policies - Validate tokens on every request - Log authentication events for security monitoring

Error Handling

Handle authentication errors gracefully
Implement proper logout on token expiration
Provide clear error messages to users

Example Implementation

Here’s a complete example of implementing authentication in JavaScript:

class AuthService {
  constructor(baseUrl) {
    this.baseUrl = baseUrl;
    this.accessToken = null;
    this.refreshToken = null;
  }

  async login(email, password) {
    const response = await fetch(`${this.baseUrl}/token?grant_type=password`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ email, password }),
    });

    if (!response.ok) {
      throw new Error("Login failed");
    }

    const data = await response.json();
    this.accessToken = data.access_token;
    this.refreshToken = data.refresh_token;

    return data.user;
  }

  async refreshAccessToken() {
    if (!this.refreshToken) {
      throw new Error("No refresh token available");
    }

    const response = await fetch(
      `${this.baseUrl}/token?grant_type=refresh_token`,
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ refresh_token: this.refreshToken }),
      }
    );

    if (!response.ok) {
      throw new Error("Token refresh failed");
    }

    const data = await response.json();
    this.accessToken = data.access_token;
    this.refreshToken = data.refresh_token;
  }

  async makeAuthenticatedRequest(url, options = {}) {
    const headers = {
      Authorization: `Bearer ${this.accessToken}`,
      "Content-Type": "application/json",
      ...options.headers,
    };

    let response = await fetch(url, { ...options, headers });

    // If token expired, try to refresh
    if (response.status === 401) {
      await this.refreshAccessToken();
      headers["Authorization"] = `Bearer ${this.accessToken}`;
      response = await fetch(url, { ...options, headers });
    }

    return response;
  }

  logout() {
    this.accessToken = null;
    this.refreshToken = null;
  }
}

Next Steps

User Management

Learn about user lifecycle and profile management

Security Concepts

Understand security features and best practices

Integration Guides

Step-by-step implementation guides

API Reference

Detailed API documentation

Get Started

Core Concepts

Guides

Overview

Authentication Flow

Token Types

Access Token

Refresh Token

Service Role Key

Authentication Methods

Security Headers

Rate Limiting

Error Handling

JWT Token Structure

Best Practices

Example Implementation

Next Steps

User Management

Security Concepts

Integration Guides

API Reference

​Overview

​Authentication Flow

​Token Types

​Access Token

​Refresh Token

​Service Role Key

​Authentication Methods

​Security Headers

​Rate Limiting

​Error Handling

​JWT Token Structure

​Best Practices

​Example Implementation

​Next Steps

User Management

Security Concepts

Integration Guides

API Reference

Overview

Authentication Flow

Token Types

Access Token

Refresh Token

Service Role Key

Authentication Methods

Security Headers

Rate Limiting

Error Handling

JWT Token Structure

Best Practices

Example Implementation

Next Steps