AuvaDocs
Sign in

API Authentication

Every authenticated Auva API request requires a valid JWT access token. This page covers how to obtain, use, and refresh tokens.

Obtaining an Access Token

Via Login

text
POST https://auth.auva.dev/auth/login
Content-Type: application/json

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

The response includes an accessToken and sets a refreshToken cookie:

text
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "user": { ... }
}

Via Refresh

When your access token expires (after 15 minutes), silently refresh it:

text
POST https://auth.auva.dev/auth/refresh
# Refresh token is sent automatically via cookie

Returns a fresh access token:

text
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs..."
}

Using the Token

Include the token in all authenticated requests:

text
GET https://auth.auva.dev/user/me
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Token Lifecycle

text
Login → Access Token (15 min) → Expires → Refresh → New Access Token
                                                      ↑
                                           Refresh Token (7 days) ──┘

Auto-Refresh Pattern (Frontend)

The AuthProvider in Auva frontend apps handles this automatically:

text
async function withAuthRetry(executor: (token: string) => Promise<Response>) {
  let response = await executor(accessToken);
  
  if (response.status === 401) {
    // Token expired, try refreshing
    const newToken = await refreshAccessToken();
    if (!newToken) throw new Error("Session expired");
    response = await executor(newToken);
  }
  
  return response;
}

Always implement the retry-on-401 pattern. It ensures your users never see unnecessary login prompts for expired tokens.

Credentials Mode

When making requests from a browser, always include credentials:

text
fetch('https://auth.auva.dev/auth/refresh', {
  method: 'POST',
  credentials: 'include',  // Required for cookies
});

This is required for the refresh token cookie to be sent.