authelia-api/POSTMAN_GUIDE.md

Authelia API - Postman Collection

This directory contains Postman files for testing and interacting with the Authelia API.

Files

• authelia-api.postman_collection.json - Main Postman collection with all API endpoints
• authelia-api.postman_environment.json - Environment variables for easy configuration
• src/test_bulk.json - Example request body for bulk user creation

Setup Instructions

1. Import into Postman

1. Open Postman
2. Click Import button
3. Select both the collection and environment files
4. Click Import

2. Configure Environment

1. In Postman, select the "Authelia API" environment from the environment dropdown (top-right)
2. Click the eye icon next to the environment name
3. Set the following variables:

Variable	Value	Description
base_url	http://127.0.0.1:8080	API base URL (default)
bearer_token	Your session.secret	Required - Get from Authelia config

3. Get Your Bearer Token

The initial bearer token is your Authelia session.secret:

# Extract from Authelia configuration
grep -A2 "session:" /opt/authelia/configuration.yml | grep "secret:" | awk '{print $2}'

Example token: 5DdUKe12k6niaaekpTeB0H35A48xmTWBWJcI3AOoqPA=

Security Note: This token provides full API access. Keep it secure!

API Endpoints

Health Check

• GET /api/health
• No authentication required
• Returns API status and version

Bulk Create Users

• POST /api/users/bulk
• Requires Bearer token
• Creates multiple users with auto-generated passwords
• Example request body in src/test_bulk.json

List Users

• GET /api/users
• Requires Bearer token
• Lists all users in the system

Delete User

• DELETE /api/users/{username}
• Requires Bearer token
• Deletes a user by username

Testing Workflow

1. Health Check: Verify API is running
2. Bulk Create: Add test users (see example below)
3. List Users: Confirm users were created
4. Delete User: Clean up test users

Example: Create Test Users

Use the pre-configured request in the collection, or modify the body:

{
  "users": [
    {
      "username": "test.user1",
      "display_name": "Test User One",
      "email": "test1@example.com",
      "groups": ["users", "developers"]
    },
    {
      "username": "test.user2",
      "display_name": "Test User Two",
      "email": "test2@example.com",
      "groups": ["users"]
    }
  ]
}

Response Examples

Health Check

{
  "status": "ok",
  "version": "dev",
  "time": "2026-04-02T00:00:00Z"
}

Bulk Create Success

{
  "success": true,
  "created": 2,
  "users": [
    {
      "username": "john.doe",
      "display_name": "John Doe",
      "email": "john.doe@example.com",
      "placeholder_password": "aB3$fG7!kL9*mN2@pQ",
      "status": "created"
    }
  ]
}

List Users

[
  {
    "username": "john.doe",
    "display_name": "John Doe",
    "email": "john.doe@example.com",
    "groups": ["users", "admins"],
    "disabled": false,
    "created_at": "2026-04-02 00:00:00",
    "updated_at": "2026-04-02 00:00:00"
  }
]

Troubleshooting

401 Unauthorized

• Check that bearer_token is set in environment
• Verify token matches Authelia session.secret
• Ensure Authorization header is present

Connection Refused

• Verify Authelia API is running: systemctl status authelia-api
• Check API port: Default is 127.0.0.1:8080
• Ensure firewall allows local connections

400 Bad Request

• Validate JSON request body format
• Check required fields: username, display_name, email
• Ensure email contains '@' symbol

Next Steps

1. Test API with actual user data
2. Configure SMTP for email onboarding (if needed)
3. Set up monitoring/alerting for API health
4. Consider rotating bearer tokens for production

Related Resources

• Authelia API Source Code
• Installation Guide
• Authelia Documentation