74 lines
3.8 KiB
Markdown
74 lines
3.8 KiB
Markdown
# Gem Track Backend - API Documentation Overview
|
|
|
|
Welcome to the backend API reference for **Gem Track**! This guide is designed to help frontend developers and API integrators understand the available resources, authentication flow, and how to start making requests locally.
|
|
|
|
## Detailed OpenAPI Reference
|
|
|
|
The backend uses **TSOA**, which means that our API routes and schemas are strongly-typed and automatically generated.
|
|
|
|
You can access the full Interactive Swagger API documentation by navigating to:
|
|
👉 **[http://localhost:3000/docs](http://localhost:3000/docs)**
|
|
|
|
*(Make sure you have started your Docker environment via `docker compose up` first)*
|
|
|
|
From the Swagger UI, you can:
|
|
- **Test Endpoints**: Execute API requests directly from your browser.
|
|
- **View Schemas**: Inspect the exact JSON payload shapes for requests and responses.
|
|
- **Download Specification**: Grab the raw `swagger.json` file to auto-generate frontend SDKs/clients using generic tools (like OpenAPI Generator or Orval).
|
|
|
|
---
|
|
|
|
## High-Level Capabilities
|
|
|
|
The API exposes endpoints divided into distinct domains:
|
|
|
|
### 1. Tenancy (`/api/v1/tenants`)
|
|
Gem Track is a multi-tenant application. Every organization runs in its own tenant container.
|
|
- **`POST /api/v1/tenants`**: Onboard a new tenant (this sets up default DB rows, billing plans, roles, and permissions).
|
|
- **`GET /api/v1/tenants/{tenantId}`**: Fetch details about an active tenant.
|
|
|
|
### 2. Authentication (`/api/v1/auth`)
|
|
Tokens are issued via JWT and must be provided natively in the `Authorization` header (`Bearer <token>`).
|
|
- **`POST /api/v1/auth/register`**: Enroll the first administrator user for a new tenant.
|
|
- **`POST /api/v1/auth/login`**: Acquire a JWT credential by authenticating.
|
|
- **`GET /api/v1/auth/me`**: Returns profile info, active roles, and authorization scopes (permissions) for the current user.
|
|
|
|
### 3. User Management (`/api/v1/users`)
|
|
- **`POST /api/v1/users`**: Directly create a new user profile inside a tenant.
|
|
- **`POST /api/v1/users/invite`**: Issue an invitation to a new team member.
|
|
- **`PATCH /api/v1/users/{userId}/roles`**: Assign operational security roles (`tenant_admin` or `tenant_user`).
|
|
- **`PATCH /api/v1/users/{userId}/status`**: Adjust user standing (active/suspended).
|
|
- **`GET /api/v1/users/{userId}`**: Extract scoped profile details.
|
|
|
|
### 4. Billing (`/api/v1/billing`)
|
|
Tracks the assigned tier usage context logic.
|
|
- **`GET /api/v1/billing/subscription`**: Pull the current subscription parameters (e.g., Free vs Pro vs Enterprise limits).
|
|
- **`POST /api/v1/billing/subscription/plan`**: Downgrade/Upgrade the overarching plan context constraints.
|
|
- **`GET /api/v1/billing/history`**: Return paginated historical statement data.
|
|
|
|
### 5. Task Management (`/api/v1/tasks`)
|
|
Agile tracking mechanics for users operating within the ecosystem.
|
|
- **`POST /api/v1/tasks`**: Map a new task context.
|
|
- **`GET /api/v1/tasks`**: Read parameters, scope visibility based on user tenant constraints.
|
|
- **`PATCH /api/v1/tasks/{taskId}` & Sub-Tasks**: Mutate progress milestones spanning assignments.
|
|
|
|
### 6. Document Management (`/api/v1/documents`)
|
|
- **`POST /api/v1/documents`**: Implements multi-part form data uploads for handling physical file ingest scaling.
|
|
- **`GET /api/v1/documents`**: Retrieves associated files stored alongside records.
|
|
|
|
---
|
|
|
|
## Common Workflows
|
|
|
|
### System Setup
|
|
1. **Create the Tenant**: Hit `POST /api/v1/tenants`
|
|
2. **Create the Admin User**: Hit `POST /api/v1/auth/register` using the UUID returned from step 1.
|
|
3. **Login in App**: Send credentials via `POST /api/v1/auth/login` and persist the generated `accessToken`.
|
|
|
|
### Authenticating Requests
|
|
Once you have the `accessToken` from login, all requests tagged with the lock icon in Swagger (which require the `bearerAuth` security schema) must include the following header:
|
|
|
|
```http
|
|
Authorization: Bearer <your-access-token>
|
|
```
|