PSA/docs/api/api_overview.md

API Overview

👉 New to our APIs? Check out our Getting Started Guide for a quick introduction to using our APIs.

1. Introduction

This document outlines the design and architecture of the Alga PSA APIs. Our APIs are implemented using Next.js for the backend and take a REST-ish approach, leveraging Next.js API routes along with our existing actions system.

📝 Note: The Alga PSA hosted environment is available at algapsa.com. If you are running an on-premise installation, replace this with your configured domain.

2. API Editions

Our APIs are segmented into two editions:

Community Edition (CE)

• Located in the server/src/api/ directory
• Available in both CE and EE deployments
• Core functionality APIs
• Accessible to all deployments

Enterprise Edition (EE)

• Located in the ee/server/src/api/ directory
• Only available in EE deployments
• Advanced/premium features
• Current EE-only APIs:
  • Tenant Provisioning API (see tenant_provisioning_api.md)
  • Hudu Integration Status API (see Section 6)

The edition is controlled by the EDITION environment variable:

• EDITION=community for CE deployments
• EDITION=enterprise for EE deployments

3. Core Architecture

• Technology Stack:
  • Next.js: APIs are built using Next.js API routes, which integrate seamlessly into the existing Next.js application.
  • Node.js: Underlying runtime environment.
  • Zod: Used for schema validation of incoming requests.
  • NextAuth Augmentation: Our NextAuth integration (defined in server/src/types/next-auth.ts) includes extended fields such as proToken, tenant, and user_type. These fields support role/permission claims in the JWT for authorization via our RBAC infrastructure.
  • Existing Actions: APIs leverage existing server actions for business logic implementation.

4. Security Framework

• Authentication:
  • API key-based authentication for all API endpoints
  • API keys are associated with specific users and tenants
  • Keys can be created, managed, and revoked through dedicated API endpoints
  • Middleware validates API keys and attaches user context
  • API keys can be set to expire and are automatically deactivated
  • API key management through server actions:
    • createApiKey: Create a new API key
    • listApiKeys: List all API keys for the current user
    • deactivateApiKey: Deactivate an API key
• Authorization:
  • Role-Based Access Control (RBAC) system integration
  • NextAuth configuration extends User, Session, and JWT types
  • Role claims embedded in JWTs during authentication
  • Middleware enforces role-based permissions
  • 401/403 responses for authentication/authorization failures

5. Standard Conventions

API Structure

• Controllers: Contain business logic
• Routes: Define Next.js API endpoints
• Schemas: Zod validation for request/response payloads
• Actions: Integration with server actions
• Middleware: Authentication and authorization handlers

Common Patterns

• RESTful endpoint design
• Consistent error handling
• Standard HTTP status codes
• Structured response formats

API Key Management

API keys can be managed through the user interface by navigating to your User Profile settings and scrolling to the "API Keys" section. The underlying implementation uses server actions in server/src/lib/actions/apiKeyActions.ts:

• Creating API Keys:

  const result = await createApiKey(
    "Development API key",           // Optional description
    "2026-02-10T12:00:00Z"          // Optional expiration date
  );
  // Returns:
  {
    api_key_id: "uuid",
    api_key: "generated-api-key",    // Only shown once upon creation
    description: "Development API key",
    created_at: "2025-02-10T12:00:00Z",
    expires_at: "2026-02-10T12:00:00Z"
  }
  

• Listing API Keys:

  const keys = await listApiKeys();
  // Returns:
  [
    {
      api_key_id: "uuid",
      description: "Development API key",
      created_at: "2025-02-10T12:00:00Z",
      last_used_at: "2025-02-10T12:30:00Z",
      expires_at: "2026-02-10T12:00:00Z",
      active: true
    }
  ]
  

• Deactivating API Keys:

  await deactivateApiKey("api-key-id");
  

• Using API Keys: Include the API key in the x-api-key header for all API requests:

  GET /api/some-endpoint
  x-api-key: your-api-key-here
  

6. Available APIs

Community Edition APIs

=======

The following REST API groups are available in the Community Edition under the base path /api/v1/:

• API Rate Limiting and Webhooks
• Unified Full-Text Search
• Tickets — Create, read, update, and close service tickets; manage comments, time entries, assignments, and files. Includes ticket bundling and asset links (see below). GET /api/v1/tickets supports a fields query parameter for sparse field sets; pass fields=tags to include each ticket's tag array in the response — each entry contains tag_id, tag_text, background_color, and text_color.
• Assets — Register hardware assets, schedule maintenance, map relationships between devices, drive RMM actions, and link assets to tickets (see below).
• Users — Create and administer user accounts, manage passwords and two-factor authentication, and read roles, teams, and effective permissions.
• Billing — Access contracts, contract lines, invoices, and billing analytics.
• Additional endpoints: companies (clients), contacts, projects, boards, categories, priorities, statuses, time entries, schedules, and more.

Ticket Bundling

When multiple tickets describe the same underlying issue, they can be grouped under one master ticket using the bundle sub-resource at /api/v1/tickets/{id}/bundle. This feature is available to both PSA and AlgaDesk tenants.

Method	Path	Purpose
GET	/tickets/{id}/bundle	Return the ticket's bundle role (master, child, or standalone), the master ticket, children, and settings
POST	/tickets/{id}/bundle	Create a bundle with {id} as master. Requires child_ticket_ids (array of UUIDs); accepts optional mode (link_only or sync_updates, default sync_updates)
DELETE	/tickets/{id}/bundle	Detach all children and remove bundle settings
POST	/tickets/{id}/bundle/children	Add additional child tickets to an existing bundle
DELETE	/tickets/{id}/bundle/children/{childId}	Remove one child; bundle settings are cleaned up when the last child is removed
POST	/tickets/{id}/bundle/promote	Promote a child ticket to become the new master
PUT	/tickets/{id}/bundle/settings	Update mode and/or reopen_on_child_reply for the bundle

Bundle modes:

• link_only — links tickets visually without propagating state changes to children
• sync_updates — propagates the master ticket's status changes to all children (default)

Asset ↔ Ticket Links

Assets and tickets can be linked to each other (the same association surfaced in the asset and ticket detail UIs). The link is a single record readable and writable from either side.

Method	Path	Purpose
GET	/assets/{id}/tickets	List tickets linked to an asset
POST	/assets/{id}/tickets	Link a ticket to an asset. Requires ticket_id; accepts optional relationship_type (default affected) and notes
DELETE	/assets/{id}/tickets/{ticketId}	Remove the link between an asset and a ticket
GET	/tickets/{id}/assets	List assets linked to a ticket
POST	/tickets/{id}/assets	Link an asset to a ticket. Requires asset_id; accepts optional relationship_type (default affected) and notes
DELETE	/tickets/{id}/assets/{assetId}	Remove the link between a ticket and an asset

Permissions: the asset-side routes require asset:update plus ticket:read; the ticket-side routes require ticket:update plus asset:read. In each case you need update on the resource whose links you are changing and read on the one you reference.

Enterprise Edition APIs

• Tenant Provisioning API: Enables partner-driven tenant management. See tenant_provisioning_api.md for details.
• Hudu Integration Status: GET /api/integrations/hudu returns connection health for the tenant's Hudu integration: status, baseUrl, connectedAt, lastSyncedAt, and passwordAccess (whether the Hudu API key can reach the password endpoints). Connection setup, company mapping, and asset layout mapping are configured through the Alga PSA UI at Settings → Integrations → Hudu, not via REST. Requires the system_settings read permission; available on EE deployments with the Hudu feature enabled. See hudu.md for the full admin guide.

7. Development Guidelines

Edition-Specific Considerations

• CE APIs should focus on core functionality
• EE APIs can depend on CE components but not vice versa
• Use feature flags for edition-specific functionality
• Test both editions during development
• Document edition requirements clearly

General Guidelines

Integration with Actions System

• APIs should leverage existing server actions where possible
• Standardized error mapping to HTTP responses
• Consistent business logic processing

Logging and Monitoring

• Request details and error logging
• Performance monitoring
• Error rate tracking
• Audit trail maintenance

Testing Requirements

• Unit tests for validation and business logic
• Integration tests for API endpoints
• Authentication/authorization test cases
• Error handling verification

Documentation Standards

• API specifications should include:
  • Endpoint descriptions
  • Request/response schemas
  • Authentication requirements
  • Example requests/responses
  • Error scenarios and handling

8. Future Considerations

• API Documentation: OpenAPI/Swagger integration
• Webhook Support: For asynchronous operations
• Rate Limiting: Request throttling implementation
• Versioning Strategy: API versioning guidelines
• Security Reviews: Regular security assessment and updates

9. Conclusion

This architecture provides a foundation for building secure, maintainable, and extensible APIs across both Community and Enterprise editions. It emphasizes security through robust authentication and authorization, maintainability through consistent patterns and documentation, and extensibility through modular design and standardized interfaces. The edition-based segmentation ensures that advanced features are properly isolated while maintaining a cohesive development experience.