Authentication API

Learn how to authenticate with the Archivus API using JWT tokens or API keys.

Overview

Archivus supports two authentication methods:

  1. JWT Tokens - For web and mobile applications (tokens expire)
  2. API Keys - For server-to-server integrations (never expire)

JWT Authentication

Login

Authenticate and receive a JWT token:

POST /api/v1/auth/login

Request:

{
  "email": "user@example.com",
  "password": "your-password",
  "tenant_subdomain": "your-tenant"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "refresh_eyJhbGciOiJIUz...",
  "user": {
    "id": "user-uuid",
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "role": "user"
  },
  "tenant": {
    "id": "tenant-uuid",
    "name": "Acme Corp",
    "subdomain": "acme-corp"
  }
}

Code Examples:

import requests

response = requests.post(
    "https://api.archivus.app/api/v1/auth/login",
    json={
        "email": "user@example.com",
        "password": "your-password",
        "tenant_subdomain": "your-tenant"
    }
)
data = response.json()
token = data["token"]

const response = await fetch('https://api.archivus.app/api/v1/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'your-password',
    tenant_subdomain: 'your-tenant'
  })
});
const data = await response.json();
const token = data.token;

Using JWT Token

Include the token in the Authorization header:

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -H "X-Tenant-Subdomain: your-tenant" \
     https://api.archivus.app/api/v1/documents

Register

Create a new user account:

POST /api/v1/auth/register

Request:

{
  "email": "newuser@example.com",
  "password": "securepassword",
  "first_name": "Jane",
  "last_name": "Smith",
  "account_type": "individual",
  "tenant_name": "Jane's Workspace"
}

Response: Same as login response

Refresh Token

Refresh an expired access token:

POST /api/v1/auth/refresh

Request:

{
  "refresh_token": "refresh_eyJhbGciOiJIUz..."
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "refresh_eyJhbGciOiJIUz..."
}

Logout

Invalidate the current session:

POST /api/v1/auth/logout

Headers:

Authorization: Bearer YOUR_JWT_TOKEN
X-Tenant-Subdomain: your-tenant

Response:

{
  "message": "Logged out successfully"
}

API Key Authentication

Generate API Key

Create an API key for server-to-server integrations:

POST /api/v1/api-keys

Headers:

Authorization: Bearer YOUR_JWT_TOKEN
X-Tenant-Subdomain: your-tenant

Request:

{
  "name": "Production Integration",
  "scopes": ["documents:read", "documents:write"]
}

Response:

{
  "id": "key_abc123",
  "api_key": "ak_live_abc123def456...",
  "name": "Production Integration",
  "created_at": "2025-12-16T10:30:00Z"
}

** Important:** The API key is only shown once. Store it securely!

Using API Key

Include the API key in the X-API-Key header:

curl -H "X-API-Key: ak_live_YOUR_API_KEY" \
     https://api.archivus.app/api/v1/documents

Code Examples:

import requests

headers = {
    "X-API-Key": "ak_live_YOUR_API_KEY"
}
response = requests.get(
    "https://api.archivus.app/api/v1/documents",
    headers=headers
)

const response = await fetch('https://api.archivus.app/api/v1/documents', {
  headers: {
    'X-API-Key': 'ak_live_YOUR_API_KEY'
  }
});

List API Keys

Get all API keys for your account:

GET /api/v1/api-keys

Headers:

Authorization: Bearer YOUR_JWT_TOKEN
X-Tenant-Subdomain: your-tenant

Response:

{
  "api_keys": [
    {
      "id": "key_abc123",
      "name": "Production Integration",
      "created_at": "2025-12-16T10:30:00Z",
      "last_used_at": "2025-12-16T14:30:00Z"
    }
  ]
}

Revoke API Key

Delete an API key:

DELETE /api/v1/api-keys/key_abc123

Headers:

Authorization: Bearer YOUR_JWT_TOKEN
X-Tenant-Subdomain: your-tenant

CSRF Protection

For mutation requests (POST, PUT, DELETE), you need a CSRF token:

Get CSRF Token 

GET /api/v1/auth/csrf-token

Response:

{
  "csrf_token": "csrf_1234567890abcdef"
}

Use CSRF Token

Include the CSRF token in the X-CSRF-Token header:

curl -X POST https://api.archivus.app/api/v1/documents/upload \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "X-CSRF-Token: csrf_1234567890abcdef" \
  -F "file=@document.pdf"

Password Management

Forgot Password

Request a password reset email:

POST /api/v1/auth/forgot-password

Request:

{
  "email": "user@example.com"
}

Reset Password

Reset password with token from email:

POST /api/v1/auth/reset-password

Request:

{
  "token": "reset_token_from_email",
  "new_password": "newSecurePassword123!"
}

Change Password

Change password while authenticated:

POST /api/v1/auth/change-password

Headers:

Authorization: Bearer YOUR_JWT_TOKEN
X-Tenant-Subdomain: your-tenant

Request:

{
  "current_password": "oldPassword123!",
  "new_password": "newPassword123!"
}

Email Verification

Verify Email

Verify email address with token:

POST /api/v1/auth/verify-email

Request:

{
  "token": "verification_token_from_email"
}

Resend Verification

Resend verification email:

POST /api/v1/auth/resend-verification

Headers:

Authorization: Bearer YOUR_JWT_TOKEN
X-Tenant-Subdomain: your-tenant

OAuth Authentication

Google OAuth 

POST /api/v1/auth/oauth/google

Request:

{
  "code": "oauth_code_from_google",
  "redirect_uri": "https://yourapp.com/callback"
}

Apple OAuth 

POST /api/v1/auth/oauth/apple

Request:

{
  "code": "oauth_code_from_apple",
  "redirect_uri": "https://yourapp.com/callback"
}

GitHub OAuth 

POST /api/v1/auth/oauth/github

Request:

{
  "code": "oauth_code_from_github",
  "redirect_uri": "https://yourapp.com/callback"
}

Error Responses

Invalid Credentials

Status: 401 Unauthorized

{
  "error": "invalid_credentials",
  "code": "INVALID_CREDENTIALS",
  "message": "Invalid email or password"
}

Token Expired

Status: 401 Unauthorized

{
  "error": "token_expired",
  "code": "TOKEN_EXPIRED",
  "message": "JWT token has expired"
}

Invalid API Key

Status: 401 Unauthorized

{
  "error": "invalid_api_key",
  "code": "INVALID_API_KEY",
  "message": "Invalid API key"
}

Missing CSRF Token

Status: 403 Forbidden

{
  "error": "csrf_token_required",
  "code": "CSRF_TOKEN_REQUIRED",
  "message": "CSRF token is required for this request"
}

Best Practices

Security

  1. Never commit tokens - Store in environment variables
  2. Use HTTPS - Always use HTTPS in production
  3. Rotate API keys - Regularly rotate API keys
  4. Use scopes - Limit API key permissions with scopes

Token Management

  1. Store securely - Use secure storage (keychain, secrets manager)
  2. Refresh before expiry - Refresh tokens before they expire
  3. Handle expiration - Implement token refresh logic
  4. Invalidate on logout - Always invalidate tokens on logout

Error Handling

  1. Check status codes - Handle 401 and 403 errors
  2. Retry with refresh - Retry with refreshed token on 401
  3. Log authentication failures - Monitor for security issues

Next Steps

Questions? Check the FAQ or contact support@ubiship.com