Skip to main content

Authentication

The Festivalism API uses a two-tier authentication system to ensure secure access to resources.

Overview​

  1. Client Authentication: Every API request requires a client token (except public endpoints)
  2. User Authentication: User-specific operations require an additional user token

Client Authentication​

Step 1: Create a Client​

First, create a client application to get your credentials. You can do this through the Client Management page.

Step 2: Exchange Credentials for Token​

Use your client ID and secret to obtain a client token:

Endpoint: POST /auth/client

Request:

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "X-F-Authorization",
  "expires": 2592000
}

Example:

curl -X POST https://api.festivalism.com/auth/client \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "abc123",
    "client_secret": "your-secret-key"
  }'

Step 3: Use Client Token​

Include the client token in the X-F-Authorization header for all API requests:

curl -X GET https://api.festivalism.com/festivals \
  -H "X-F-Authorization: your-client-token"

Token Expiration: Client tokens expire after 30 days. You'll need to exchange your credentials again to get a new token.

User Authentication​

For user-specific operations (like creating resources, accessing user data), you need to authenticate as a user.

Step 1: Login as User​

Endpoint: POST /auth/user

Headers:

  • X-F-Authorization: Your client token (required)

Request:

{
  "email": "user@example.com",
  "password": "user-password"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "X-F-Authentication",
  "expiresIn": 43200,
  "headerName": "X-F-Authentication"
}

Example:

curl -X POST https://api.festivalism.com/auth/user \
  -H "X-F-Authorization: your-client-token" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123"
  }'

Step 2: Use User Token​

Include both tokens in your requests:

  • X-F-Authorization: Client token
  • X-F-Authentication: User token
curl -X GET https://api.festivalism.com/users/me \
  -H "X-F-Authorization: your-client-token" \
  -H "X-F-Authentication: your-user-token"

Token Expiration: User tokens expire after 12 hours.

Password Management​

Forgot Password​

Endpoint: POST /auth/forgot-password

Request:

{
  "email": "user@example.com"
}

Reset Password​

Endpoint: POST /auth/reset-password

Request:

{
  "email": "user@example.com",
  "token": "reset-token-from-email",
  "newPassword": "new-secure-password"
}

Change Password​

Endpoint: PUT /auth/change-password

Headers:

  • X-F-Authorization: Client token
  • X-F-Authentication: User token

Request:

{
  "currentPassword": "old-password",
  "newPassword": "new-password"
}

Error Responses​

401 Unauthorized​

{
  "error": "Missing X-F-Authorization header"
}

or

{
  "error": "Invalid token"
}

400 Bad Request​

{
  "error": "email and password are required"
}

Security Best Practices​

  1. Never expose your client secret - Keep it secure and never commit it to version control
  2. Use HTTPS - Always make API requests over HTTPS in production
  3. Store tokens securely - Don't expose tokens in client-side code or logs
  4. Handle token expiration - Implement token refresh logic in your application
  5. Use environment variables - Store credentials in environment variables, not in code