Admin API Specifications

Detailed API specifications for the Law Firm Admin Provisioning API system.

Overview

These specifications are organized by API domain and feature area. Each specification corresponds to a specific API endpoint and includes:

• User Stories: Clear description of the feature's purpose
• Scenarios: Concrete examples with acceptance criteria
• Request/Response Specs: API contract details in tables
• Requirements Mapping: Traceability to functional requirements

Directory Structure

📁 firms/

Law firm tenant management

• Create Law Firm - POST /admin/law-firms
• List Law Firms - GET /admin/law-firms
• Get Law Firm - GET /admin/law-firms/{lawFirmId}

📁 users/

User and lawyer provisioning

• Provision User - POST /admin/law-firms/\{lawFirmId\}/users
• Add Credential - POST .../users/\{userId\}/credentials
• List Credentials - GET .../users/\{userId\}/credentials
• Remove Credential - DELETE .../users/\{userId\}/credentials/\{credentialId\}
• List Profiles - GET /admin/law-firms/\{lawFirmId\}/profiles
• Lookup Auth Users - GET /admin/auth-users

📁 logto-bridge/

Logto organization member management

• List Org Members - GET /admin/logto/orgs/\{lawFirmId\}/members
• Add Org Member - POST .../members
• Get Org Member - GET .../members/\{userId\}
• Remove Org Member - DELETE .../members/\{userId\}
• Update Member Roles - PUT .../members/\{userId\}/roles
• List Org Roles - GET /admin/logto/org-roles

Note: Logto organizations are automatically created when law firms are created, and automatically deleted when law firms are deleted. No manual binding or sync is required.

📁 access-grants/

Resource access control

• List Resource Types - GET /admin/resource-types
• List Resource Subtypes - GET /admin/resource-types/\{type\}/subtypes
• Search Grants - GET /admin/resource-access-grants
• List Grants for Resource - GET /admin/resources/\{type\}/\{id\}/access-grants
• Create Grant - POST /admin/resources/\{type\}/\{id\}/access-grants
• Revoke Grant - DELETE /admin/resources/\{type\}/\{id\}/access-grants/\{userId\}/\{level\}
• List Subresource Grants - GET .../subresources/\{subtype\}/\{subid\}/access-grants
• Create Subresource Grant - POST .../subresources/\{subtype\}/\{subid\}/access-grants
• Revoke Subresource Grant - DELETE .../subresources/\{subtype\}/\{subid\}/access-grants/\{userId\}/\{level\}

📁 capabilities/

User capabilities and policies

• Get Resource Policies - GET .../users/\{userId\}/resource-policies
• Get User Capabilities - GET .../users/\{userId\}/capabilities

📁 support-access/

Support impersonation (act-as)

• Start Support Session - POST /admin/support-access/requests
• List Support Sessions - GET /admin/support-access/sessions
• Get Support Session - GET /admin/support-access/sessions/\{id\}
• Revoke Support Session - DELETE /admin/support-access/sessions/\{id\}
• Acquire Resource Lock - POST /admin/resource-locks
• Release Resource Lock - DELETE /admin/resource-locks/\{id\}

📁 shared/

Common test fixtures and steps

• Background Steps - Reusable Given steps
• API Simplifications - Logto org management changes
• Data Fixtures - Test data setup
• Common Schemas - Shared data structures

Specification Format

All specifications follow this structure:

# Feature Name

**API Endpoint**: `METHOD /path`
**Priority**: P1/P2/P3
**User Story**: As an admin, I want to...

## Overview
Brief description of the feature

## Scenarios

### Scenario 1: Success case

**Given**:
- Preconditions (state, auth, data)

**When**:
- Action (API request with payload)

**Then**:
- Expected outcome (status, response, side effects)
- Tables for structured data validation

### Scenario 2: Error case
...

## Request Specification
Tables showing all parameters

## Response Specification
Example responses with explanations

## Requirements Mapping
FR-001, FR-002, etc.

Key Benefits

✅ Testable: Each scenario can be automated ✅ Clear: Structured format with concrete examples ✅ Complete: Tables provide comprehensive API details ✅ Traceable: Requirements mapped to scenarios ✅ Maintainable: One file per endpoint, easy to update

API Coverage

Domain	Endpoints	Features	Status
Firms	3	3	✅ Complete
Users	6	6	✅ Complete
Logto Bridge	6	6	✅ Complete
Access Grants	9	9	✅ Complete
Capabilities	2	2	✅ Complete
Support Access	6	6	✅ Complete
Total	32	32	100% Complete

How to Use

For Developers

1. Read the user story to understand the goal
2. Review scenarios for behavior examples
3. Check request/response specs for API contract
4. Implement to satisfy all scenarios

For QA Engineers

1. Convert scenarios to automated tests
2. Use scenario steps as test cases
3. Reference data fixtures in shared/
4. Generate test reports mapped to requirements

For Product Managers

1. Review user stories for feature clarity
2. Validate scenarios cover all cases
3. Check priorities align with roadmap
4. Use as communication tool with stakeholders

Contributing

When adding new features:

1. Create new .md file in appropriate directory
2. Follow the specification format template
3. Include comprehensive scenarios (success + errors)
4. Use tables for complex data
5. Map to requirements (FR-XXX)
6. Add to this index under correct domain