Skip to main content

Authentication

Authentication guide for the FishingLog API.

Overview​

The FishingLog API uses AWS Cognito for authentication with JWT Bearer tokens.

AWS Cognito Configuration​

  • User Pool ID: us-east-2_TZtGx1T3X
  • Client ID: 6i1opt39o2n5h5ihq471l1ev07
  • Region: us-east-2

Authentication Flow​

1. Login​

Endpoint: POST /api/auth/login

Request:

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

Response:

{
  "access_token": "eyJraWQiOiJ...",
  "id_token": "eyJraWQiOiJ...",
  "refresh_token": "eyJjdHkiOiJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}

2. Use Token in Requests​

Include the token in the Authorization header:

Authorization: Bearer <id_token>

Important: Use the id_token (not access_token) for API authentication. The id_token contains user identity claims and is properly signed for the API.

3. Refresh Token​

Endpoint: POST /api/auth/refresh

Request:

{
  "refreshToken": "eyJjdHkiOiJ..."
}

Response:

{
  "access_token": "eyJraWQiOiJ...",
  "id_token": "eyJraWQiOiJ...",
  "refresh_token": "eyJjdHkiOiJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Token Types​

Access Token​

  • Used for calling AWS services
  • Do not use for API authentication
  • Contains AWS service permissions

ID Token​

  • Use this for API authentication
  • Contains user identity claims
  • Properly signed for the client ID
  • Includes user email, username, and Cognito ID

Refresh Token​

  • Used to get new access and ID tokens
  • Long-lived (typically 30 days)
  • Store securely

User Auto-Creation​

On first login, if a user doesn't exist in the database, the API automatically creates a User record using information from the JWT token claims.

Creating Users​

See Cognito User Management for instructions on creating and managing Cognito users via AWS CLI.

Token Expiration​

  • Access Token: 1 hour
  • ID Token: 1 hour
  • Refresh Token: 30 days (typically)

Use the refresh token to get new tokens before expiration.

Authorization​

Public Endpoints​

These endpoints don't require authentication:

  • GET /health - Health check
  • POST /api/auth/login - Login
  • POST /api/auth/refresh - Refresh token

Protected Endpoints​

All other endpoints require authentication:

Authorization: Bearer <id_token>

Role-Based Access​

Some endpoints require specific roles:

  • Admin: Admin panel endpoints (/api/admin/*)
  • Moderator: Content moderation endpoints
  • DNR: Department of Natural Resources access
  • Researcher: Research data access

See Admin Roles & Permissions for details.

Testing Authentication​

Using Insomnia​

  1. Use the Login (Simple) request
  2. Copy the id_token from the response
  3. Add to environment variable access_token
  4. All authenticated requests will automatically include the token

See Testing Guide for details.

Using cURL​

# Login
curl -X POST https://api-staging.reelog.app/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"user@example.com","password":"password"}'

# Use token in request
curl -X GET https://api-staging.reelog.app/api/user/me \
  -H "Authorization: Bearer <id_token>"

Troubleshooting​

"Invalid token" Error​

  • Verify you're using the id_token (not access_token)
  • Check token hasn't expired
  • Regenerate token if needed

"Unauthorized" Error​

  • Ensure token is included in Authorization header
  • Verify token format: Bearer <token>
  • Check user exists in Cognito

"Forbidden" Error​

Security Best Practices​

  1. Never commit tokens to version control
  2. Use environment variables for tokens
  3. Store refresh tokens securely
  4. Rotate tokens regularly
  5. Use HTTPS in production
  6. Validate tokens on every request

Additional Resources​