AuvaDocs
Sign in

Authentication

Auva uses a centralized authentication system powered by Auva Auth (auth.auva.dev). Every product in the ecosystem authenticates through this single API, giving users one account across all services.

How It Works

Token Architecture

Auva Auth uses a dual-token system:

TokenTypeLifetimeStorage
Access TokenJWT15 minutesMemory / Authorization header
Refresh TokenOpaque7 daysHTTP-only secure cookie

The access token is short-lived for security. When it expires, the client silently calls the refresh endpoint to get a new one: with zero user interruption.

Authentication Endpoints

Register a new account

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

{
  "name": "Mohanad Alrwaihy",
  "username": "mohanad",
  "email": "mohanad@auva.dev",
  "password": "your-secure-password",
  "birthdate": "2000-01-15",
  "gender": "male"
}

Response 201 Created:

text
{
  "message": "Account created successfully"
}

Login

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

{
  "email": "mohanad@auva.dev",
  "password": "your-secure-password"
}

Response 200 OK:

text
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "usr_abc123",
    "name": "Mohanad Alrwaihy",
    "username": "mohanad",
    "email": "mohanad@auva.dev",
    "avatar": null,
    "createdAt": "2024-01-15T00:00:00.000Z"
  }
}

The login response also sets an HTTP-only refreshToken cookie. This cookie is used automatically by the browser for subsequent token refresh requests.

Refresh Token

text
POST https://auth.auva.dev/auth/refresh
# No body required: the refresh token is sent via cookie

Response 200 OK:

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

Get Current User

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

Response 200 OK:

text
{
  "id": "usr_abc123",
  "name": "Mohanad Alrwaihy",
  "username": "mohanad",
  "email": "mohanad@auva.dev",
  "bio": "Building the future.",
  "avatar": null,
  "profileLinks": [],
  "emailVerified": true,
  "createdAt": "2024-01-15T00:00:00.000Z"
}

Logout

text
POST https://auth.auva.dev/auth/logout
# Clears the refresh token cookie

Password Management

Forgot Password

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

{
  "email": "mohanad@auva.dev"
}

Reset Password

text
POST https://auth.auva.dev/auth/reset-password/{token}
Content-Type: application/json

{
  "password": "new-secure-password"
}

Change Password (Authenticated)

text
POST https://auth.auva.dev/user/change-password
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

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

Frontend Integration

Using the AuthProvider (React)

Every Auva frontend application wraps its component tree with the AuthProvider:

text
// layout.tsx
import { AuthProvider } from "@/components/providers/AuthProvider";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <AuthProvider>{children}</AuthProvider>
      </body>
    </html>
  );
}

Then use the useAuth() hook anywhere in your app:

text
"use client";
import { useAuth } from "@/components/providers/AuthProvider";

export function UserProfile() {
  const { user, isInitializing, logout } = useAuth();

  if (isInitializing) return <p>Loading...</p>;
  if (!user) return <a href="/login">Sign in</a>;

  return (
    <div>
      <p>Hello, {user.name}!</p>
      <button onClick={logout}>Sign out</button>
    </div>
  );
}

The useAuth() hook must be called inside a component wrapped by AuthProvider. Calling it outside will throw an error.

Security Best Practices

SSO Integration

Add "Sign in with Auva" to your own app.

User Profiles

Managing user data, avatars, and profile links.