API Gateway: REST API Contract¶

Version	Date	Author	Change Description
1.0	2025-09-11	Senior Systems Analyst	Initial contract for local password authentication.
2.0	2025-09-11	Senior Systems Analyst	Complete rewrite for Google SSO. Replaced login endpoints with OAuth 2.0 flow, removed password fields, added invitation model.

1.0 Introduction¶

This document provides a comprehensive and formal definition of the HTTP RESTful API exposed by the API Gateway. This contract is the "single source of truth" for frontend developers consuming the API. All endpoints, request/response schemas, and status codes are detailed herein.

Base URL: /api/v1

2.0 Common Data Structures & Conventions¶

2.1 User Object¶

Represents a user account.

{
  "userId": "c7a8b9d0-e1f2-g3h4-i5j6-k7l8m9n0o1p2",
  "email": "user@our-company.com",
  "displayName": "Jane Doe",
  "status": "Active",
  "createdAt": "2025-09-11T12:00:00Z",
  "updatedAt": "2025-09-11T12:30:00Z",
  "lastLoginAt": "2025-09-11T12:30:00Z"
}

status: Can be Active, Inactive, or Invited.

2.2 Error Response¶

When an API call fails, the response will use the appropriate HTTP status code and include a JSON body with the following structure:

{
  "error": {
    "code": 403,
    "message": "You do not have permission to perform this action."
  }
}

3.0 Authentication Endpoints (Google SSO)¶

These endpoints manage the SSO flow. They do not return JSON but instead use HTTP redirects.

`GET /auth/google/login`¶

Initiates the Google SSO login process.

Description: When a user accesses this endpoint, the API Gateway generates the appropriate Google authentication URL and immediately redirects the user's browser to it.
Request: No body required.
Successful Response:
- Code: 302 Found
- Headers: Location: https://accounts.google.com/o/oauth2/v2/auth?...

`GET /auth/google/callback`¶

The callback endpoint that Google redirects to after successful or failed authentication.

Description: The gateway receives the callback from Google, processes the authorization_code by calling the backend AuthService, creates a session, sets a cookie, and redirects the user to the frontend dashboard.
Successful Response (on session creation):
- Code: 302 Found
- Headers:
  - Set-Cookie: session_token=...; HttpOnly; Secure; Path=/
  - Location: /dashboard
Error Response (e.g., non-corporate account):
- Code: 302 Found
- Headers: Location: /login?error=access_denied

4.0 User Self-Service Endpoints¶

Endpoints for an authenticated user to manage their own profile.

`GET /users/me`¶

Retrieves the profile of the currently logged-in user.

Permission Required: Authenticated User

Successful Response (200 OK):

{
  "userId": "c7a8b9d0-e1f2-g3h4-i5j6-k7l8m9n0o1p2",
  "email": "user@our-company.com",
  "displayName": "Jane Doe",
  "status": "Active",
  // ... other user fields
}

`PUT /users/me`¶

Updates the profile of the currently logged-in user.

Permission Required: Authenticated User
Request Body:
```
{
  "displayName": "Jane A. Doe"
}
```
Successful Response (200 OK): Returns the updated User Object.

5.0 Administrative Endpoints: User Management¶

Endpoints for administrators to manage all users.

`POST /users/invite`¶

Invites a new user, creating a pre-provisioned account.

Permission Required: admin:user:invite

Request Body:

{
  "email": "new.user@our-company.com",
  "roleIds": ["a1b2...", "c3d4..."],
  "groupIds": ["e5f6...", "g7h8..."]
}

Successful Response (201 Created): Returns the new User Object with status: "Invited".

`GET /users`¶

Lists all users with optional filtering.

Permission Required: admin:user:list
Query Parameters:
- email (string): Filter by exact email match.
- name (string): Filter by partial display name match.
- status (string): Filter by Active, Inactive, or Invited.

Successful Response (200 OK):

{
  "users": [
    // Array of User Objects
  ],
  "nextPageToken": "abc123xyz"
}

`GET /users/{userId}`¶

Retrieves a single user by their ID.

Permission Required: admin:user:list
Successful Response (200 OK): Returns the User Object.

`PUT /users/{userId}`¶

Updates a user's details, status, or role/group assignments.

Permission Required: admin:user:edit

Request Body:

{
  "displayName": "Johnathan Doe",
  "status": "Inactive",
  "roleIds": ["c3d4..."],
  "groupIds": ["e5f6..."]
}

Successful Response (200 OK): Returns the updated User Object.

`GET /users/{userId}/effective-permissions`¶

Retrieves a user's calculated set of all permissions.

Permission Required: admin:user:view_permissions

Successful Response (200 OK):

{
  "permissions": [
    {
      "permissionName": "document:edit",
      "sourceDescription": "Inherited from Group: Marketing -> Role: Editor"
    },
    {
      "permissionName": "document:view",
      "sourceDescription": "Inherited from Role: Standard User"
    }
  ]
}

6.0 Administrative Endpoints: Role Management¶

`POST /roles`¶

Permission Required: admin:role:create
Description: Creates a new role.
Request Body: { "name": "...", "description": "...", "permissionIds": ["..."] }
Response (201 Created): The new Role object.

`GET /roles`¶

Permission Required: admin:role:list
Description: Lists all roles.
Response (200 OK): Array of Role objects.

`GET /roles/{roleId}`¶

Permission Required: admin:role:list
Description: Gets a single role.
Response (200 OK): A Role object.

`PUT /roles/{roleId}`¶

Permission Required: admin:role:edit
Description: Updates a role.
Request Body: { "name": "...", "description": "...", "permissionIds": ["..."] }
Response (200 OK): The updated Role object.

`DELETE /roles/{roleId}`¶

Permission Required: admin:role:delete
Description: Deletes a role.
Response (204 No Content): No body.

7.0 Administrative Endpoints: Group Management¶

`POST /groups`¶

Permission Required: admin:group:create
Description: Creates a new group.
Request Body: { "name": "...", "description": "...", "memberIds": ["..."], "roleIds": ["..."] }
Response (201 Created): The new Group object.

`GET /groups`¶

Permission Required: admin:group:list
Description: Lists all groups.
Response (200 OK): Array of Group objects.

`GET /groups/{groupId}`¶

Permission Required: admin:group:list
Description: Gets a single group.
Response (200 OK): A Group object.

`PUT /groups/{groupId}`¶

Permission Required: admin:group:edit
Description: Updates a group.
Request Body: { "name": "...", "description": "...", "memberIds": ["..."], "roleIds": ["..."] }
Response (200 OK): The updated Group object.

`DELETE /groups/{groupId}`¶

Permission Required: admin:group:delete
Description: Deletes a group.
Response (204 No Content): No body.

8.0 Administrative Endpoints: Audit Trail¶

`GET /audit-logs`¶

Retrieves the security audit trail logs.

Permission Required: admin:audit:view
Query Parameters:
- userId (string): Filter by actor or target user ID.
- eventType (string): Filter by a specific event type (e.g., USER_PROVISIONED).
- startDate (string, ISO 8601 format).
- endDate (string, ISO 8601 format).

Successful Response (200 OK):

{
  "logs": [
    {
      "logId": "12345",
      "timestamp": "2025-09-11T14:00:00Z",
      "actor": { "userId": "...", "email": "admin@..." },
      "eventType": "USER_STATUS_CHANGED",
      "target": { "userId": "...", "email": "target@..." },
      "details": { "oldStatus": "Active", "newStatus": "Inactive" }
    }
  ]
}

9.0 AI-Enhanced Workflow Endpoint¶

`POST /ai`¶

Provides a single, stateful endpoint for all user interactions with the AI assistant.

Permission Required: Authenticated User
Description: This endpoint is the sole entry point for the AI-Enhanced Workflow. It handles initial queries, continuations of existing conversations, and confirmations of execution plans.

Request Body:

{
  "sessionId": "string (optional, for continuing conversations)",
  "query": "string (user's text input)",
  "confirmation": { // Optional: Sent when a user confirms a plan
    "planId": "string",
    "confirmed": true
  }
}

Successful Responses (200 OK): The response object's structure depends on the state of the conversation.
- Scenario 1: Plan Requires Confirmation
If the user's query results in a data-modifying plan, the service returns a description of the plan for the user to confirm.
```
{
  "type": "plan_confirmation_required",
  "planId": "a1b2-c3d4-e5f6-g7h8",
  "description": "This will add user 'jdoe' to the 'auditors' group."
}
```
- Scenario 2: Final Answer
If the query was read-only or after a plan has been confirmed and executed, the service returns the final, synthesized answer.
```
{
  "type": "final_answer",
  "sessionId": "z9y8-x7w6-v5u4-t3s2",
  "response": "Success: User 'jdoe' has been added to the 'auditors' group."
}
```
Error Responses:
- 400 Bad Request: The request body is malformed.
- 403 Forbidden: The user is not authorized to perform the requested action.
- 500 Internal Server Error: An unexpected error occurred in the AI workflow.

API Gateway: REST API Contract¶

1.0 Introduction¶

2.0 Common Data Structures & Conventions¶

2.1 User Object¶

2.2 Error Response¶

3.0 Authentication Endpoints (Google SSO)¶

GET /auth/google/login¶

GET /auth/google/callback¶

4.0 User Self-Service Endpoints¶

GET /users/me¶

PUT /users/me¶

5.0 Administrative Endpoints: User Management¶

POST /users/invite¶

GET /users¶

GET /users/{userId}¶

PUT /users/{userId}¶

GET /users/{userId}/effective-permissions¶

6.0 Administrative Endpoints: Role Management¶

POST /roles¶

GET /roles¶

GET /roles/{roleId}¶

PUT /roles/{roleId}¶

DELETE /roles/{roleId}¶

7.0 Administrative Endpoints: Group Management¶

POST /groups¶

GET /groups¶

GET /groups/{groupId}¶

PUT /groups/{groupId}¶

DELETE /groups/{groupId}¶

8.0 Administrative Endpoints: Audit Trail¶

GET /audit-logs¶

9.0 AI-Enhanced Workflow Endpoint¶

POST /ai¶

`GET /auth/google/login`¶

`GET /auth/google/callback`¶

`GET /users/me`¶

`PUT /users/me`¶

`POST /users/invite`¶

`GET /users`¶

`GET /users/{userId}`¶

`PUT /users/{userId}`¶

`GET /users/{userId}/effective-permissions`¶

`POST /roles`¶

`GET /roles`¶

`GET /roles/{roleId}`¶

`PUT /roles/{roleId}`¶

`DELETE /roles/{roleId}`¶

`POST /groups`¶

`GET /groups`¶

`GET /groups/{groupId}`¶

`PUT /groups/{groupId}`¶

`DELETE /groups/{groupId}`¶

`GET /audit-logs`¶

`POST /ai`¶