Authentication

FreePas API uses JWT (JSON Web Tokens) for authentication. All API endpoints (except public RSVP pages) require a valid access token.

Login

To obtain an access token, send a POST request to the login endpoint:

POST /api/v1/auth/login

{
  "username": "user@example.com",
  "password": "securePassword123"
}

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

Using the Access Token

Include the access token in the Authorization header of all authenticated requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

Refresh Token

Access tokens expire after 1 hour. Use the refresh token to obtain a new access token without re-authenticating:

POST /api/v1/auth/refresh

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response:
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

Logout

Invalidate your current session by calling the logout endpoint:

POST /api/v1/auth/logout
Authorization: Bearer YOUR_ACCESS_TOKEN

OAuth 2.0

FreePas also supports OAuth 2.0 authentication with Google and Microsoft. See our OAuth Integration Guide for details.

Security Best Practices

Never commit API keys or tokens to version control
Use environment variables to store sensitive credentials
Rotate access tokens regularly
Implement proper error handling for authentication failures
Use HTTPS for all API requests