Authentication API

Learn how to authenticate with the OPTIMAGE API using JWT session tokens via HTTP-only cookies.

Authentication Overview

OPTIMAGE uses JWT (JSON Web Token) based authentication with HTTP-only cookies for security. This approach prevents XSS attacks while maintaining a smooth user experience.

✓Secure: HTTP-only cookies prevent JavaScript access
✓Automatic: Browsers handle cookie management
✓Session-based: Tokens expire after 7 days of inactivity

Sign Up Endpoint

Create a new user account and receive an authentication cookie.

POST https://api.optimage.com/api/v1/sign-up

Request Body

{
  "email": "[email protected]",
  "password": "securePassword123"
}

Response (200 OK)

{
  "id": "user_1234567890",
  "email": "[email protected]",
  "createdAt": "2025-12-04T10:30:00Z"
}

Error Responses

400 Bad Request - Invalid email format or password too weak

409 Conflict - Email already exists

Example (cURL)

curl -X POST https://api.optimage.com/api/v1/sign-up \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securePassword123"
  }' \
  -c cookies.txt

Example (JavaScript)

const response = await fetch('https://api.optimage.com/api/v1/sign-up', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  credentials: 'include', // Important: Include cookies
  body: JSON.stringify({
    email: '[email protected]',
    password: 'securePassword123'
  })
});

const user = await response.json();
console.log('User created:', user);

Sign In Endpoint

Authenticate an existing user and receive a session cookie.

POST https://api.optimage.com/api/v1/sign-in

Request Body

{
  "email": "[email protected]",
  "password": "securePassword123"
}

Response (200 OK)

{
  "user": {
    "id": "user_1234567890",
    "email": "[email protected]",
    "createdAt": "2025-12-04T10:30:00Z"
  },
  "quota": {
    "plan": "free",
    "limit": 500,
    "used": 142,
    "remaining": 358,
    "resetDate": "2026-01-01T00:00:00Z"
  }
}

Error Responses

400 Bad Request - Missing email or password

401 Unauthorized - Invalid credentials

Example (cURL)

curl -X POST https://api.optimage.com/api/v1/sign-in \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securePassword123"
  }' \
  -c cookies.txt

Example (JavaScript)

const response = await fetch('https://api.optimage.com/api/v1/sign-in', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  credentials: 'include',
  body: JSON.stringify({
    email: '[email protected]',
    password: 'securePassword123'
  })
});

if (response.ok) {
  const data = await response.json();
  console.log('Signed in:', data.user);
  console.log('Quota remaining:', data.quota.remaining);
} else {
  console.error('Sign in failed:', response.status);
}

Sign Out Endpoint

Invalidate the current session and clear the authentication cookie.

POST https://api.optimage.com/api/v1/sign-out

Response (200 OK)

{
  "message": "Signed out successfully"
}

Example (cURL)

curl -X POST https://api.optimage.com/api/v1/sign-out \
  -b cookies.txt

Example (JavaScript)

await fetch('https://api.optimage.com/api/v1/sign-out', {
  method: 'POST',
  credentials: 'include'
});

console.log('Signed out successfully');

Session Management

OPTIMAGE uses secure HTTP-only cookies for session management with the following properties:

•httpOnly: true - Cookie cannot be accessed via JavaScript
•secure: true - Cookie only sent over HTTPS
•sameSite: Lax - Protection against CSRF attacks
•maxAge: 7 days - Session expires after 7 days of inactivity

Tip: Always use credentials: 'include' in your fetch requests to ensure cookies are sent with API calls. Without this, authentication will fail.

Getting Current User

Retrieve information about the currently authenticated user, including quota details.

GET https://api.optimage.com/api/v1/config

Response (200 OK)

{
  "user": {
    "id": "user_1234567890",
    "email": "[email protected]",
    "createdAt": "2025-12-04T10:30:00Z"
  },
  "quota": {
    "plan": "free",
    "limit": 500,
    "used": 142,
    "remaining": 358,
    "resetDate": "2026-01-01T00:00:00Z"
  }
}

Error Responses

401 Unauthorized - Not authenticated or session expired

Example (JavaScript)

const response = await fetch('https://api.optimage.com/api/v1/config', {
  credentials: 'include'
});

if (response.ok) {
  const { user, quota } = await response.json();
  console.log('Current user:', user.email);
  console.log('Quota:', `${quota.used}/${quota.limit}`);
} else {
  console.error('Not authenticated');
}