Skip to main content

​
Overview

ArcHive uses JWT (JSON Web Token) based authentication. The authentication flow involves:
  1. Register or login to receive access and refresh tokens
  2. Include the access token in the Authorization header for protected endpoints
  3. Refresh the access token when it expires using the refresh token
  4. Logout to invalidate both tokens

​
Authentication Flow

​
Access Tokens

Access tokens are short-lived JWT tokens used to authenticate API requests. Include them in the Authorization header: 
Authorization: Bearer YOUR_ACCESS_TOKEN

​
Refresh Tokens

Refresh tokens are long-lived tokens used to obtain new access tokens without requiring the user to log in again.

​
Register User

Create a new user account and receive authentication tokens.
POST /api/auth/register
curl -X POST https://api.archive.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123!",
    "firstName": "John",
    "lastName": "Doe"
  }'

​
Request Body

​
email
string
required
Valid email address (converted to lowercase)
​
password
string
required
Password meeting security requirements:
  • Minimum 8 characters
  • Maximum 64 characters
  • At least one uppercase letter
  • At least one lowercase letter
  • At least one number
  • At least one special character
​
firstName
string
required
User’s first name (1-50 characters)
​
lastName
string
required
User’s last name (1-50 characters)

​
Response

​
message
string
Success message: “Registration successful!”
​
user
object
User information object
​
accessToken
string
JWT access token for API authentication
​
refreshToken
string
JWT refresh token for obtaining new access tokens
{
  "message": "Registration successful!",
  "user": {
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

​
Login

Authenticate with existing credentials to receive tokens.
POST /api/auth/login
curl -X POST https://api.archive.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123!"
  }'

​
Request Body

​
email
string
required
Valid email address (converted to lowercase)
​
password
string
required
User’s password

​
Response

​
message
string
Success message: “Login successful!”
​
user
object
User information object
​
accessToken
string
JWT access token for API authentication
​
refreshToken
string
JWT refresh token for obtaining new access tokens
{
  "message": "Login successful!",
  "user": {
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

​
Refresh Access Token

Obtain a new access token using a valid refresh token.
POST /api/auth/refresh
curl -X POST https://api.archive.com/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

​
Request Body

​
refreshToken
string
required
Valid refresh token obtained from login or registration

​
Response

​
message
string
Success message: “Token refreshed successfully!”
​
accessToken
string
New JWT access token for API authentication
​
refreshToken
string
New JWT refresh token (token rotation for security)
{
  "message": "Token refreshed successfully!",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

​
Logout

Invalidate both access and refresh tokens to end the session.
POST /api/auth/logout
curl -X POST https://api.archive.com/api/auth/logout \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

​
Headers

​
Authorization
string
required
Bearer token with the access token: Bearer YOUR_ACCESS_TOKEN

​
Request Body

​
refreshToken
string
required
Refresh token to invalidate

​
Response

​
message
string
Success message: “Logout successful.”
{
  "message": "Logout successful."
}

​
Security Features

​
Token Blacklisting

When a user logs out, both the access and refresh tokens are blacklisted to prevent reuse.

​
Password Requirements

Passwords must meet the following security criteria:
  • Minimum 8 characters, maximum 64 characters
  • At least one uppercase letter (A-Z)
  • At least one lowercase letter (a-z)
  • At least one number (0-9)
  • At least one special character

​
Rate Limiting

Authentication endpoints are protected with rate limiting:
  • Registration & Login: Standard rate limiting
  • Token Refresh: Strict rate limiting to prevent abuse

​
JWT Algorithm

Tokens are signed using the HS256 (HMAC with SHA-256) algorithm.

​
Error Responses

Common authentication errors:

​
Invalid Credentials

{
  "success": false,
  "message": "Invalid email or password",
  "statusCode": 401
}

​
Token Expired

{
  "success": false,
  "message": "Access token expired",
  "statusCode": 401
}

​
Validation Error

{
  "success": false,
  "message": "Validation failed",
  "statusCode": 400,
  "details": {
    "password": ["Password must contain at least one uppercase letter"]
  }
}

​
Best Practices

Never store tokens in localStorage or sessionStorage in web applications. Use secure, httpOnly cookies or memory storage with proper security measures.
Refresh access tokens before they expire to maintain a seamless user experience. Implement token refresh logic in your API client.
The API implements token rotation - each refresh request returns a new refresh token. Always update your stored refresh token after a successful refresh.
Call the logout endpoint when detecting suspicious activity, password changes, or security-related events.

Build docs developers (and LLMs) love

Get started for freeTalk to us