Skip to main content

Authentication

The Rivegen API uses JWT (JSON Web Token) Bearer authentication. All protected endpoints require a valid access token in the request header.

Obtaining Tokens​

Login​

Authenticate with username and password to receive access and refresh tokens:

curl -X POST "https://api.rivegen.com/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "password": "securepassword"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": {
    "id": "user_123",
    "username": "johndoe",
    "email": "john@example.com",
    "role": "user"
  }
}

See User Management API for API details.

Using Tokens​

Include the access token in the Authorization header for all protected endpoints:

Authorization: Bearer <access_token>

Example:

curl -X GET "https://api.rivegen.com/api/rivers" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token Refresh​

Access tokens are short-lived (typically 1 hour). Use the refresh token to obtain a new access token:

curl -X POST "https://api.rivegen.com/api/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Response:

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

See authentication endpoints for details.

Token Refresh Strategy​

Implement automatic token refresh in your client:

  1. Store both access_token and refresh_token securely
  2. Before each API call, check if the access token is expired (or near expiration)
  3. If expired, use the refresh token to obtain a new access token
  4. If the refresh token is also expired, redirect to login

Password Reset​

If you forget your password:

  1. Request a password reset using the authentication endpoint
  2. Check your email for a reset token
  3. Reset password using the reset endpoint

Security Best Practices​

  • Never expose tokens in client-side code, URLs, or logs
  • Use HTTPS only - tokens should never be transmitted over HTTP
  • Store tokens securely - use secure storage mechanisms (keychain, encrypted storage)
  • Implement token rotation - refresh tokens regularly
  • Logout on token expiration - clear stored tokens and redirect to login

See Also​