Athena Archive API

A FastAPI-based digital archive management system with OAuth2 authentication via Authentik.

Requirements:

• MySQL 8.4 LTS (MariaDB not supported - requires JSON type)
• Python 3.13+
• Authentik SSO provider

Notes:

• A system user is created with id 1000 on startup
• All GET endpoints are public
• POST/PUT/DELETE operations require authentication
• Admin endpoints require 'admin' or 'system' role

Quick Start

# Install dependencies
uv sync

# Run migrations
make migrate

# Start development server
make run

Authentication

This API uses OAuth2 bearer token authentication via Authentik.

Development Mode (Local Testing)

For local development, you can bypass OAuth with static tokens:

1. Set DEV_MODE=true in .env (already set by default)
2. Use one of the following tokens:
   • devtoken - Regular user (can create/edit resources)
   • devadmintoken - Admin user (can access admin endpoints)

In FastAPI docs (/docs):

1. Click "Authorize" button
2. Enter: devtoken (or devadmintoken for admin access)
3. Test any protected endpoints

With curl:

# Regular user
curl -H "Authorization: Bearer devtoken" http://localhost:8000/auth/me

# Admin user
curl -H "Authorization: Bearer devadmintoken" http://localhost:8000/auth/me

IMPORTANT: Set DEV_MODE=false in production!

Production Authentication

Use the interactive API docs at http://localhost:8000/docs to test with real Authentik tokens:

1. Click the "Authorize" button
2. Enter your bearer token from Authentik
3. Test any protected endpoints

Making Authenticated Requests

# Get current user info
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/auth/me

# Create an item (requires authentication)
curl -X POST -H "Authorization: Bearer $TOKEN" http://localhost:8000/item/

User Roles

• Researcher:
  • search and read privileges of public and private content.
  • This is the default role for new users.
  • Sidebar Visibility:
    • All links in the "Content" Category
    • "Workflow" Category: Add potential content, view "unprocessed" list.\
  • Cannot create, edit, or delete content.
• Author:
  • all permissions of Researcher.
  • create, edit, and delete own items and media.
  • additional sidebar visibility:
    • "Workflow" Category: Orphaned items and Orphaned media.
• Editor:
  • all permissions of Author.
  • create, edit, any items and media.
• Supervisor:
  • all permissions of Editor.
  • additional sidebar visibility:
    • "Administration" Category: User Management, view and run tasks.
• Global Administrator: full installation privileges.

Users are automatically created on first login from Authentik JWT claims.

Development

Importing legacy Omeka S database models into Omeka-S-Py

Get a copy of your Omeka database:

sudo mysqldump -u root -p Omeka > omeka_backup.sql
# move the sql file to the data/ directory

Set up and run the Docker container:

docker-compose up -d

Database

https://alembic.sqlalchemy.org/en/latest/ops.html

Generate SQLAlchemy models from existing database

uv add sqlacodegen sqlalchemy pymysql cryptography
uv run python -m sqlacodegen "mysql+pymysql://root:password@localhost:3306/omeka" --outfile models_sa.py
uv remove sqlacodegen sqlalchemy pymysql cryptography

Initial Alembic setup and migration

uv run python -m alembic init migrations
uv run python -m alembic revision --autogenerate -m "Initial migrations"
uv run python -m alembic upgrade head

Display the current revision for a database: alembic current View migrations history: alembic history --verbose Revert all migrations: alembic downgrade base Revert migrations one by one: alembic downgrade -1 Apply all migrations:alembic upgrade head Apply migrations one by one: alembic upgrade +1 Display all raw SQL: alembic upgrade head --sql Reset the database: alembic downgrade base && alembic upgrade head

https://medium.com/@johnidouglasmarangon/using-migrations-in-python-sqlalchemy-with-alembic-docker-solution-bd79b219d6a

Squash Migrations

DO NO COMMIT THE SQUASHED MIGRATION FOR PRODUCTION USE WITHOUT TESTING FIRST

# delete old revision files
rm -f migrations/versions/*.py
uv run python -m alembic revision -m "squashed migration"
uv run python -m alembic stamp head --purge
uv run python -m alembic current