blaisadmin/FlockPal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated api docs

Browse Source
This commit is contained in:
blaisadmin
2026-04-14 23:13:17 -04:00
parent 37c8265320
commit 40900a0968
1 changed files with 91 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API_REFERENCE.md
+91 -33
View File
@@ -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 <auth_token>
Authorization: Bearer <token>
```
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.