Apikeys

[Mikefluff]

Feature: Complete API Key Management System

Overview

This merge request introduces a comprehensive API key management system for Hi.Events, enabling users to create, manage, and revoke API keys for programmatic access to the platform. This feature includes both backend API endpoints and a complete frontend interface for managing API keys.

🎯 Key Features Added

1. API Key Management Backend

• API Key Creation: Generate personal access tokens with customizable permissions and expiration dates
• API Key Listing: Retrieve all API keys for the authenticated user
• API Key Revocation: Securely delete/revoke API keys
• Role-based Access Control: Only ADMIN users can manage API keys
• Flexible Permissions: Support for scoped abilities (users, accounts, events, etc.)

2. Frontend User Interface

• Complete API Key Management Page: Located in Account Settings
• Interactive API Key Creation Modal: User-friendly form with permission selection
• API Key Display Table: Shows name, abilities, expiry date, and management options
• Secure Token Display: One-time display of plaintext tokens with copy functionality
• Confirmation Dialogs: Safe deletion with user confirmation

3. Developer Experience

• Comprehensive API Documentation: Complete endpoint documentation with examples
• API Routes Summary: Quick reference for all available endpoints
• TypeScript Support: Full type definitions for API key structures
• Internationalization: Multi-language support for UI components

📋 Changes Made

Backend Changes (backend/)

New API Endpoints

POST /api/api-keys              // Create new API key
GET /api/api-keys               // List all API keys
DELETE /api/api-keys/{token_id} // Revoke API key

Action Classes Created

• CreateApiKeyAction.php - Handles API key creation with abilities and expiration
• GetApiKeysAction.php - Retrieves user's API keys
• RevokeApiKeyAction.php - Safely revokes API keys

Security & Authorization

• Admin-only access control using minimumAllowedRole(Role::ADMIN)
• Secure token generation using Laravel Sanctum
• Proper token expiration handling

Frontend Changes (frontend/)

New Components

• ApiKeys/index.tsx - Main API key management interface
• CreateApiKeyModal/index.tsx - Modal for creating new API keys
• ApiKeyForm/index.tsx - Form component with permission selection

API Client Integration

• api-keys.client.ts - Frontend API client for key management
• Complete CRUD operations with proper error handling
• TypeScript integration with type safety

User Experience Features

• One-time Token Display: Secure modal showing plaintext token only once
• Copy-to-Clipboard: Easy token copying with visual feedback
• Permission Management: Granular control over API key abilities
• Expiration Dates: Optional token expiration with date picker
• Confirmation Dialogs: Safe deletion with user confirmation

Type Definitions (types.ts)

interface CreateApiKeyRequest {
    token_name: string;
    abilities?: string[];
    expires_at?: string;
}

interface ApiKey {
    id?: number;
    name: string;
    abilities: string[];
    expires_at?: string;
    // ... additional fields
}

interface NewApiKey {
    accessToken: ApiKey;
    plainTextToken: string;
}

Documentation

New Documentation Files

• API_DOCUMENTATION.md - Complete API documentation with all endpoints
• API_ROUTES_SUMMARY.md - Quick reference for all available routes

Features Documented

• Authentication methods (JWT + API Keys)
• All 140+ API endpoints with parameters
• Response formats and error handling
• Public vs authenticated route distinctions

🚀 API Key Capabilities

Permission Scopes Available

• Users: User management operations
• Accounts: Account configuration and settings
• Organizers: Event organizer management
• Events: Complete event management (or granular permissions)
  • Events -> General
  • Events -> Products
  • Events -> Stats
  • Events -> Attendees
  • Events -> Orders
  • Events -> Questions
• Taxes and Fees: Tax and fee management
• Full Access: All permissions (*)

Security Features

• Role-based Access: Only admins can manage API keys
• Token Expiration: Configurable expiration dates
• Secure Storage: Tokens hashed in database
• One-time Display: Plaintext tokens shown only once
• Proper Revocation: Clean token deletion

🌐 Internationalization

Translation support added for 12 languages:

• English (en)
• German (de)
• Spanish (es)
• French (fr)
• Italian (it)
• Dutch (nl)
• Portuguese (pt, pt-br)
• Russian (ru)
• Vietnamese (vi)
• Chinese (zh-cn, zh-hk)

🔧 Technical Implementation

Backend Architecture

• Laravel Sanctum: Personal access token management
• Role-based Security: Admin-only access control
• RESTful API Design: Standard HTTP methods and status codes
• Proper Exception Handling: Comprehensive error responses

Frontend Architecture

• React + TypeScript: Type-safe component development
• Mantine UI: Consistent design system
• TanStack Query: Efficient data fetching and caching
• Form Management: Robust form validation and error handling

Bug Fixes Included

• HasFactory Namespace Conflict: Resolved duplicate imports causing 500 errors
• Missing Route Definitions: Added missing API key routes causing 404 errors
• TypeScript Import Typo: Fixed CreateApiKeyReques → CreateApiKeyRequest

📊 API Statistics

• Total API Endpoints: ~140 endpoints documented
• Authenticated Routes: ~120 endpoints
• Public Routes: ~20 endpoints
• New API Key Routes: 3 endpoints added

🧪 Testing & Quality Assurance

• ✅ Functional Testing: All API key operations tested
• ✅ Security Testing: Permission validation confirmed
• ✅ UI/UX Testing: Complete user workflow verified
• ✅ Error Handling: Proper error messages and validation
• ✅ Translation Testing: Multi-language support verified

💡 Benefits

1. Developer Integration: External systems can now integrate with Hi.Events programmatically
2. Enhanced Security: Granular permission control for API access
3. User Experience: Intuitive interface for API key management
4. Scalability: Foundation for future API-driven features
5. Documentation: Complete reference for developers
6. Enterprise Ready: Professional API key management capabilities

🔮 Future Enhancements

• API usage analytics and rate limiting
• Webhook authentication using API keys
• Advanced permission scoping
• API key usage logs and monitoring

---

Checklist

• I have read the contributing guidelines
• My code is of good quality and follows the coding standards of the project
• I have tested my changes, and they work as expected
• All critical bugs have been resolved (500 and 404 errors)
• Complete API key management system implemented
• Comprehensive documentation added
• Multi-language support included
• Security best practices followed
• TypeScript types properly defined
• No breaking changes introduced

[github-actions]

Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.

---

I have read the CLA Document and I hereby sign the CLA

---

1 out of 2 committers have signed the CLA.
✅ (grablair)[https://github.com/grablair]
❌ @mikhail Savchenko
Mikhail Savchenko seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.}

[Mikefluff]

I have read the CLA Document and I hereby sign the CLA

[daveearley]

Hi @Mikefluff,

Thanks for the effort on this. From a quick look at the first few files, it seems there are some unintended changes. This is probably because the branch isn't fully up to date with develop.

I'm fully supportive of using AI to help with changes, but in this case, there are some files like the API docs that aren't essential to the feature and would be better left out. These kinds of files need constant updates and can easily fall out of sync.

I also noticed endpoints for creating roles, but I didn't see where those roles are being enforced. What was your plan for handling that?