# InvitationController

**Kind:** Controller

**Source:** [`atloria-monorepo/apps/api/src/invitation/invitation.controller.ts`](https://github.com/sherkety/atloria/blob/main/atloria-monorepo/apps/api/src/invitation/invitation.controller.ts#L21)

Public invitation endpoints (token IS the credential — no JWT required).

`InvitationController` exposes public API endpoints for invitation-based flows. The invitation token acts as the credential, so these routes intentionally do not require JWT authentication and delegate validation and invitation handling to the invitation service layer.

## Diagram

```mermaid
graph LR
  A[Invitation recipient] -->|Opens URL with invitation token| B[InvitationController]
  B -->|Extracts and validates token| C[InvitationService]
  C --> D[(Invitation storage)]
  D --> C
  C -->|Invitation result or action outcome| B
  B -->|Public HTTP response| A
```

## Usage

```ts
const apiUrl = import.meta.env.VITE_API_URL;
const token = new URLSearchParams(window.location.search).get("token");

if (!token) {
  throw new Error("Missing invitation token");
}

// Use the public invitation endpoint; no Authorization header is required.
const response = await fetch(
  `${apiUrl}/invitation/${encodeURIComponent(token)}`,
  {
    method: "GET",
    headers: {
      Accept: "application/json",
    },
  },
);

if (!response.ok) {
  throw new Error("Invitation is invalid, expired, or no longer available.");
}

const invitation = await response.json();
console.log("Invitation details:", invitation);
```

## AI Coding Instructions

- Keep invitation endpoints public: the invitation token is the credential, so do not add JWT guards unless the flow is explicitly being redesigned.
- Treat tokens as secrets; never log them, include them in analytics events, or expose them in error messages.
- Validate token format and invitation state in the service layer, including expiration, revocation, and already-used conditions.
- Keep controller methods thin: extract request parameters, call the invitation service, and return appropriate HTTP responses.
- Preserve consistent error handling so invalid or expired tokens do not reveal unnecessary information about invitations or users.

## Relationships

- MODULE_DECLARES → `get`
- MODULE_DECLARES → `accept`
- DEPENDS_ON → `InvitationService`

## Referenced By

- `InvitationModule` (MODULE_DECLARES)