Skip to main content

Authentication Token Flow

Complete guide to managing authentication tokens in the Rivegen API.

Overview​

The Rivegen API uses JWT Bearer tokens. You'll receive both an access_token (short-lived) and a refresh_token (long-lived) when you log in.

Login Flow​

1. Authenticate​

const response = await fetch("https://api.rivegen.com/api/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    username: "johndoe",
    password: "securepassword"
  })
});

const data = await response.json();
const { access_token, refresh_token } = data;

2. Store Tokens Securely​

Store tokens in secure storage (never in localStorage for production):

// Example: secure storage
secureStorage.set("access_token", access_token);
secureStorage.set("refresh_token", refresh_token);

Using Tokens​

Make Authenticated Requests​

const token = secureStorage.get("access_token");

const response = await fetch("https://api.rivegen.com/api/rivers", {
  headers: {
    Authorization: `Bearer ${token}`
  }
});

Token Refresh Flow​

Access tokens expire after 1 hour. Implement automatic refresh:

async function refreshAccessToken() {
  const refreshToken = secureStorage.get("refresh_token");
  
  const response = await fetch("https://api.rivegen.com/api/auth/refresh", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ refresh_token: refreshToken })
  });
  
  if (response.ok) {
    const data = await response.json();
    secureStorage.set("access_token", data.access_token);
    return data.access_token;
  } else {
    // Refresh token expired, redirect to login
    redirectToLogin();
  }
}

Automatic Refresh Before Expiration​

async function fetchWithAuth(url, options = {}) {
  let token = secureStorage.get("access_token");
  
  // Check if token is expired (or near expiration)
  if (isTokenExpired(token)) {
    token = await refreshAccessToken();
  }
  
  const response = await fetch(url, {
    ...options,
    headers: {
      ...options.headers,
      Authorization: `Bearer ${token}`
    }
  });
  
  // If 401, try refresh once more
  if (response.status === 401) {
    token = await refreshAccessToken();
    return fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        Authorization: `Bearer ${token}`
      }
    });
  }
  
  return response;
}

Logout​

Clear tokens on logout:

async function logout() {
  const token = secureStorage.get("access_token");
  
  await fetch("https://api.rivegen.com/api/auth/logout", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`
    }
  });
  
  // Clear local tokens
  secureStorage.remove("access_token");
  secureStorage.remove("refresh_token");
  
  redirectToLogin();
}

Best Practices​

  1. Never expose tokens in client-side code or URLs
  2. Use HTTPS only for token transmission
  3. Implement automatic refresh before token expiration
  4. Handle 401 errors gracefully with token refresh
  5. Store tokens securely using platform-specific secure storage

See Also​