Skip to content

Authentication API

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

Overview

Archivus supports two authentication methods:

  1. API Keys - For server-to-server integrations (recommended, never expire)
  2. JWT Tokens - For web and mobile applications (expire after 24 hours)

API Key Authentication

Overview

API keys provide persistent authentication ideal for backend services and integrations.

Benefits:

  • Never expire (until manually revoked)
  • Simpler integration (single header)
  • No token refresh logic needed
  • Per-key scoping and permissions

Generate API Key

Create an API key for your account.

POST /api/v1/api-keys

Headers: 

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

Request Body: 

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

Response: 

{
  "id": "key_abc123",
  "api_key": "ak_live_abc123def456ghi789jkl012mno345pqr678stu",
  "name": "Production Integration",
  "scopes": ["documents:read", "documents:write", "search:read"],
  "created_at": "2026-01-18T10:30:00Z"
}

Save Your API Key

The API key is only shown once. Store it securely - you won't be able to retrieve it again.

Using API Keys

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

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

import requests

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

List API Keys

Get all API keys for your account.

GET /api/v1/api-keys

Response: 

{
  "api_keys": [
    {
      "id": "key_abc123",
      "name": "Production Integration",
      "scopes": ["documents:read", "documents:write"],
      "created_at": "2026-01-18T10:30:00Z",
      "last_used_at": "2026-01-18T14:30:00Z"
    },
    {
      "id": "key_def456",
      "name": "Development Testing",
      "scopes": ["documents:read"],
      "created_at": "2026-01-15T09:00:00Z",
      "last_used_at": "2026-01-17T16:00:00Z"
    }
  ]
}

Revoke API Key

Delete an API key permanently.

DELETE /api/v1/api-keys/{key_id}

Response: 

{
  "message": "API key revoked successfully"
}

API Key Scopes

Available scopes for API keys:

Scope Description
documents:read Read document metadata and content
documents:write Upload, update, and delete documents
search:read Search documents
chat:read Read chat sessions and messages
chat:write Create chat sessions and ask questions
webhooks:read List webhooks
webhooks:write Create, update, and delete webhooks
workflows:read View workflows and executions
workflows:write Create and execute workflows
admin:read Read admin resources
admin:write Modify admin resources

JWT Authentication

Overview

JWT tokens provide user-specific authentication ideal for web and mobile applications.

Benefits:

  • User-specific permissions
  • Secure for browser applications
  • OAuth integration support
  • Automatic expiration

Login

Authenticate and receive a JWT token.

POST /api/v1/auth/login

Request Body: 

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

Response: 

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "refresh_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2026-01-19T10:30:00Z",
  "user": {
    "id": "user_xyz789",
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "role": "admin"
  },
  "tenant": {
    "id": "tenant_abc123",
    "name": "Acme Corp",
    "subdomain": "acme-corp",
    "tier": "pro"
  }
}

Error Responses:

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

Using JWT Tokens

Include the token in the Authorization header with the Bearer scheme:

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

const response = await fetch('https://api.archivus.app/api/v1/documents', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'X-Tenant-Subdomain': 'your-tenant'
  }
});

headers = {
    'Authorization': f'Bearer {token}',
    'X-Tenant-Subdomain': 'your-tenant'
}
response = requests.get(
    'https://api.archivus.app/api/v1/documents',
    headers=headers
)

Register

Create a new user account.

POST /api/v1/auth/register

Request Body: 

{
  "email": "newuser@example.com",
  "password": "securepassword123",
  "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 using the refresh token.

POST /api/v1/auth/refresh

Request Body: 

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

Response: 

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "refresh_eyJhbGciOiJIUz...",
  "expires_at": "2026-01-19T10:30:00Z"
}

Logout

Invalidate the current session.

POST /api/v1/auth/logout

Response: 

{
  "message": "Logged out successfully"
}

Password Management

Forgot Password

Request a password reset email.

POST /api/v1/auth/forgot-password

Request Body: 

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

Response: 

{
  "message": "Password reset email sent"
}

Reset Password

Reset password using the token from email.

POST /api/v1/auth/reset-password

Request Body: 

{
  "token": "reset_token_from_email",
  "new_password": "your_new_password123"
}

Change Password

Change password while authenticated.

POST /api/v1/auth/change-password

Headers: 

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

Request Body: 

{
  "current_password": "your_current_password",
  "new_password": "your_new_password123"
}

OAuth Authentication

Google OAuth

Authenticate using Google OAuth.

POST /api/v1/auth/oauth/google

Request Body: 

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

Response: Same as login response

Apple OAuth

Authenticate using Apple Sign In.

POST /api/v1/auth/oauth/apple

Request Body: 

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

GitHub OAuth

Authenticate using GitHub OAuth.

POST /api/v1/auth/oauth/github

Request Body: 

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

Email Verification

Verify Email

Verify email address using token from email.

POST /api/v1/auth/verify-email

Request Body: 

{
  "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

CSRF Protection

For mutation requests (POST, PUT, DELETE) from browsers, CSRF protection is required.

Get CSRF Token

GET /api/v1/auth/csrf-token

Response: 

{
  "csrf_token": "csrf_1234567890abcdef"
}

Use CSRF Token

Include 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"

Security Best Practices

Store Credentials Securely

Never Commit Secrets

Never commit API keys or tokens to version control.

# .env file (add to .gitignore)
ARCHIVUS_API_KEY=ak_live_YOUR_API_KEY
ARCHIVUS_TENANT=your-tenant

// Load from environment
const apiKey = process.env.ARCHIVUS_API_KEY;

// AWS Secrets Manager
const { SecretsManagerClient } = require('@aws-sdk/client-secrets-manager');

const secret = await secretsManager.getSecretValue({
  SecretId: 'archivus/api-key'
});

const apiKey = JSON.parse(secret.SecretString).apiKey;

Rotate API Keys

Regularly rotate API keys for security:

  1. Create a new API key
  2. Update your application to use the new key
  3. Verify the new key works
  4. Revoke the old key

Use HTTPS

Always use HTTPS in production to prevent token interception.

Handle Token Expiration

Implement automatic token refresh:

async function makeAuthenticatedRequest(url) {
  let token = getStoredToken();

  try {
    return await fetch(url, {
      headers: { 'Authorization': `Bearer ${token}` }
    });
  } catch (error) {
    if (error.code === 'TOKEN_EXPIRED') {
      token = await refreshToken();
      return await fetch(url, {
        headers: { 'Authorization': `Bearer ${token}` }
      });
    }
    throw error;
  }
}

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 or revoked API key"
}

Missing CSRF Token

Status: 403 Forbidden

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

Next Steps

  • Upload Documents

    Start using authenticated endpoints to upload documents

    Documents API

  • Create Webhooks

    Set up real-time notifications for your integration

    Webhooks API

  • Error Handling

    Learn how to handle authentication errors

    Error Reference