API Key Authentication

Inmor supports API key authentication for programmatic access to the Admin API (/api/v1/). This allows external tools and scripts to interact with the API without session cookies.

Overview

API keys provide an alternative to session-based authentication. They are useful for:

  • Automated scripts and CI/CD pipelines

  • External monitoring tools

  • Third-party integrations

Each API key is:

  • Tied to a specific Django user account

  • Stored as a SHA-256 hash (the plaintext is shown only once at creation)

  • Optionally time-limited with an expiry date

  • Revocable at any time

Command-Line Management

The apikey management command lets you create, list, and revoke API keys from the command line.

Creating a Key

python manage.py apikey create --username admin --key-name "CI deploy"
python manage.py apikey create --username admin --key-name "CI deploy" --tenant acme-corp

The plaintext key is printed to stdout so it can be captured by scripts. The --key-name flag is optional and defaults to auto-generated. The --tenant flag assigns the key to a tenant (defaults to default).

Warning

The plaintext API key is displayed only once at creation. If you lose it, you must create a new key.

Listing Keys

List keys for a specific user:

python manage.py apikey list --username admin

List keys across all users:

python manage.py apikey list --all

Output includes the key name, prefix, tenant, active status, creation date, expiry, and last-used timestamp. The --all flag adds a user column.

Revoking a Key

python manage.py apikey revoke --username admin --key-name "CI deploy"

This deactivates all active keys matching the given name for that user. Revoked keys cannot be reactivated — create a new key instead.

Creating a Key via Admin UI

Only Django superusers can create API keys through the admin interface.

  1. Log in to the Django admin at /admin/

  2. Navigate to API Keys in the sidebar

  3. Click Add API Key

  4. Fill in the form:

    • Name: A descriptive label (e.g. “CI pipeline”, “monitoring”)

    • User: The Django user this key acts as

    • Expires at: Optional expiration date/time (leave blank for no expiry)

  5. Click Save

  6. Copy the displayed key immediately – it will not be shown again

Using an API Key

Pass the key in the X-API-Key HTTP header:

curl -H "X-API-Key: YOUR_KEY_HERE" \
     https://your-server/api/v1/trustmarktypes

All /api/v1/ endpoints accept either a session cookie or an API key. Both authentication methods grant the same access.

Examples

List trust mark types:

curl -H "X-API-Key: YOUR_KEY_HERE" \
     https://your-server/api/v1/trustmarktypes

Create a subordinate:

curl -X POST \
     -H "X-API-Key: YOUR_KEY_HERE" \
     -H "Content-Type: application/json" \
     -d '{"entityid": "https://example.com", "organization": "Example Org"}' \
     https://your-server/api/v1/subordinates

Regenerate server entity statement:

curl -X POST \
     -H "X-API-Key: YOUR_KEY_HERE" \
     https://your-server/api/v1/server/entity

Managing Keys via Admin UI

Viewing Keys

In the Django admin under API Keys, you can see all keys with:

  • Name and Key Prefix (first 8 characters for identification)

  • Status (Valid/Invalid)

  • Created, Expires, and Last Used timestamps

Revoking Keys

To revoke a single key:

  1. Click on the key in the admin list

  2. Uncheck Is active

  3. Click Save

To revoke multiple keys at once:

  1. Select the keys using the checkboxes

  2. Choose Revoke selected API keys from the action dropdown

  3. Click Go

Security Best Practices

  • Always use HTTPS – API keys are sent in headers and must be encrypted in transit

  • Set expiry dates – avoid permanent keys when possible

  • Use descriptive names – makes it easy to identify and audit keys

  • Revoke unused keys – regularly review and clean up old keys

  • One key per client – don’t share keys between different services

  • Store keys securely – treat them like passwords; use environment variables or a secrets manager

How It Works

The authentication flow:

  1. Client sends request with X-API-Key: <key> header

  2. APIKeyAuthentication (in inmoradmin/auth.py) extracts the header

  3. The key is hashed with SHA-256 and looked up in the database

  4. If found, active, and not expired, the request is authenticated as the key’s associated user

  5. The last_used_at timestamp is updated

The API router in inmoradmin/api.py accepts both session and API key authentication via combined_auth, so existing session-based workflows (including the Vue frontend) continue to work unchanged.