From 40900a09685f00a6e4ed6f58250c069145e371d5 Mon Sep 17 00:00:00 2001 From: blaisadmin Date: Tue, 14 Apr 2026 23:13:17 -0400 Subject: [PATCH] updated api docs --- docs/API_REFERENCE.md | 124 +++++++++++++++++++++++++++++++----------- 1 file changed, 91 insertions(+), 33 deletions(-) diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md index 8c73c20..cb7193a 100644 --- a/docs/API_REFERENCE.md +++ b/docs/API_REFERENCE.md @@ -10,18 +10,74 @@ This document describes the HTTP API currently implemented in `backend/src/app.t ## Authentication -Most endpoints require a bearer token: +Most protected endpoints use a bearer token: ```http -Authorization: Bearer +Authorization: Bearer ``` -Tokens are created after either: +The current backend supports two token systems. + +### 1. Browser session tokens + +Browser session tokens are created after: - a successful magic-link sign-in - a successful OAuth sign-in with Google, Microsoft, or Apple -The backend redirects the browser back to the frontend with an `auth_token` query parameter after successful sign-in. Clients should store that token and send it as a bearer token on authenticated requests. +After sign-in, the backend redirects the browser back to the frontend with an `auth_token` query parameter. That `auth_token` is the browser session token. + +Example redirect: + +```text +http://localhost:3000/?auth_token=YOUR_SESSION_TOKEN +``` + +The backend stores only a hash of the session token in the database. The raw token is returned to the client once when the session is created. + +### 2. Integration tokens + +Integration tokens are created by an authenticated browser-session user through: + +- `GET /api/integration-tokens` +- `POST /api/integration-tokens` +- `DELETE /api/integration-tokens/:tokenId` + +These tokens are intended for automation tools such as n8n, scripts, and server-to-server use. + +Integration tokens are: + +- workspace-scoped +- tied to the creating user +- returned in raw form only once at creation time +- either `read_only` or `read_write` + +Use them exactly like session tokens: + +```http +Authorization: Bearer flpt_... +``` + +### Token behavior by endpoint type + +Browser-session-only endpoints: + +- `/api/auth/logout` +- `/api/auth/session` +- `/api/auth/switch-workspace` +- `/api/workspaces` +- `/api/integration-tokens` + +Endpoints that accept either browser session tokens or integration tokens: + +- `/api/workspace` +- `/api/workspace/members` +- `/api/birds` +- `/api/birds/:birdId/weights` +- `/api/birds/:birdId/vet-visits` +- `/api/transfers/draft` + +Read-only integration tokens can call read endpoints, but cannot call write endpoints. If authentication is missing or invalid, the API returns: @@ -29,19 +85,25 @@ If authentication is missing or invalid, the API returns: { "error": "Authentication required." } ``` -FlockPal now supports two bearer token types: +Browser-session-only endpoints reject integration tokens with: -- browser session tokens returned after magic-link or OAuth sign-in -- integration tokens created from the Settings UI for automation tools like n8n +```json +{ + "error": "This endpoint requires a browser session instead of an integration token." +} +``` -Integration tokens are workspace-scoped and support: +Write endpoints reject read-only integration tokens with: -- `read_only` -- `read_write` +```json +{ + "error": "That integration token is read-only." +} +``` -## How `auth_token` Is Issued +## How Browser `auth_token` Is Issued -FlockPal issues the bearer token on the backend after a successful passwordless sign-in. The client does not generate it. +FlockPal issues the browser bearer token on the backend after a successful passwordless sign-in. The client does not generate it. ### Magic-link flow @@ -70,7 +132,7 @@ Example redirect: http://localhost:3000/?auth_token=YOUR_SESSION_TOKEN ``` -### How the token is used +### How the browser token is used After the frontend receives `auth_token`, it should store it and send it on authenticated requests: @@ -78,11 +140,7 @@ After the frontend receives `auth_token`, it should store it and send it on auth Authorization: Bearer YOUR_SESSION_TOKEN ``` -### Important implementation note - -The backend stores only a hash of the session token in the database. The raw token is returned to the client once when the session is created. - -Integration tokens follow the same bearer-token header format, but they are created separately and are intended for scripts and automation tools rather than browser login. +Integration tokens use the same bearer-token header format, but they are created separately and are not used for browser login. ## Roles @@ -330,13 +388,13 @@ If you are testing locally and received a `previewUrl`, open that URL in a brows #### `POST /api/auth/logout` -Requires auth. Invalidates the current session. +Requires a browser session. Invalidates the current session. Response `204` with no body. #### `GET /api/auth/session` -Requires auth. Returns the current session context. +Requires a browser session. Returns the current session context. Response `200`: @@ -384,7 +442,7 @@ curl http://localhost:5000/api/auth/session \ #### `POST /api/auth/switch-workspace` -Requires auth. Switches the session's active workspace. +Requires a browser session. Switches the session's active workspace. Request body: @@ -466,7 +524,7 @@ Responses: #### `POST /api/transfers/draft` -Requires auth. Prepares a bird transfer to another owner email and optionally triggers a magic-link invite for that email when no user exists yet. +Requires auth with write access. Prepares a bird transfer to another owner email and optionally triggers a magic-link invite for that email when no user exists yet. Request body: @@ -500,7 +558,7 @@ Possible errors: #### `GET /api/workspaces` -Requires auth. Lists the signed-in user's workspace memberships. +Requires a browser session. Lists the signed-in user's workspace memberships. Response `200`: @@ -512,7 +570,7 @@ Response `200`: #### `POST /api/workspaces` -Requires auth. Creates a new workspace and makes the current user its `owner`. +Requires a browser session. Creates a new workspace and makes the current user its `owner`. Request body: @@ -553,7 +611,7 @@ Response `200`: #### `PUT /api/workspace` -Requires auth and role `owner` or `manager`. Updates the active workspace. +Requires auth with write access and role `owner` or `manager`. Updates the active workspace. Request body: @@ -588,7 +646,7 @@ Response `200`: #### `POST /api/workspace/members` -Requires auth and role `owner` or `manager`. Invites or upserts a workspace member. +Requires auth with write access and role `owner` or `manager`. Invites or upserts a workspace member. Request body: @@ -610,7 +668,7 @@ Response `201`: #### `DELETE /api/workspace/members/:memberId` -Requires auth and role `owner` or `manager`. Removes a non-owner member. +Requires auth with write access and role `owner` or `manager`. Removes a non-owner member. Response `204` with no body. @@ -634,7 +692,7 @@ Response `200`: #### `POST /api/birds` -Requires auth and role `owner`, `manager`, or `staff`. Creates a bird. +Requires auth with write access and role `owner`, `manager`, or `staff`. Creates a bird. Request body: @@ -671,7 +729,7 @@ Possible errors: #### `PUT /api/birds/:birdId` -Requires auth and role `owner`, `manager`, or `staff`. Updates a bird. +Requires auth with write access and role `owner`, `manager`, or `staff`. Updates a bird. Request body matches `POST /api/birds`. @@ -690,7 +748,7 @@ Possible errors: #### `DELETE /api/birds/:birdId` -Requires auth and role `owner`, `manager`, or `staff`. Deletes a bird. +Requires auth with write access and role `owner`, `manager`, or `staff`. Deletes a bird. Response `204` with no body. @@ -718,7 +776,7 @@ Response `200`: #### `POST /api/birds/:birdId/weights` -Requires auth and role `owner`, `manager`, or `staff`. Creates a weight entry. +Requires auth with write access and role `owner`, `manager`, or `staff`. Creates a weight entry. Request body: @@ -759,7 +817,7 @@ Response `200`: #### `POST /api/birds/:birdId/vet-visits` -Requires auth and role `owner`, `manager`, or `staff`. Creates a vet visit. +Requires auth with write access and role `owner`, `manager`, or `staff`. Creates a vet visit. Request body: @@ -872,7 +930,7 @@ Use the returned token in your automation tool: Authorization: Bearer flpt_... ``` -#### `DELETE /api/integration-tokens/{tokenId}` +#### `DELETE /api/integration-tokens/:tokenId` Requires a browser session. Revokes an integration token owned by the current user in the active workspace.