Members, sessions and tokens
Members are the people who use the dashboard and the API. Each has a role, and can create personal access tokens that act as them.
Check for accounts
GET/v1/admin/auth/bootstrap
Auth: None.
How many members exist, so a fresh install can show "create the first account" instead of a login nobody can pass. Set FEATUREKIT_ADMIN_EMAIL and FEATUREKIT_ADMIN_PASSWORD to create the first one on start.
Responses
200 OK Found.
{
"members": 1
}
Common errors (500)
{
"error": "INTERNAL_ERROR"
}
Example
curl http://127.0.0.1:3000/v1/admin/auth/bootstrap
Sign in
POST/v1/admin/auth/login
Auth: None.
Sets the fk_session cookie: HttpOnly, SameSite=Strict, and Secure off localhost. Limited to 10 attempts a minute per caller.
Body
| Field | Type | Required | Description |
|---|---|---|---|
email | string | yes | |
password | string | yes |
Responses
{
"member": {
"id": "5d1f0c2a-8b3e-4f6a-9c7d-2e1b0a9f8e7d",
"email": "ana@acme.com",
"name": "Ana",
"role": "owner",
"hasPassword": true,
"lastLoginAt": "2026-11-18T09:12:44.318Z",
"createdAt": "2026-11-17T10:00:00.000Z"
}
}
{
"error": "INVALID_BODY",
"message": "email: Invalid email address; password: Invalid input: expected string, received undefined"
}
{
"error": "CREDENTIALS_REJECTED",
"message": "email or password is wrong"
}
Common errors (429, 400, 413, 500)
{
"error": "RATE_LIMITED",
"retryAfterSeconds": 12
}
{
"error": "INVALID_JSON",
"message": "request body is not valid JSON"
}
{
"error": "PAYLOAD_TOO_LARGE",
"message": "body exceeds 4096 bytes"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -X POST http://127.0.0.1:3000/v1/admin/auth/login \
-H "Content-Type: application/json" \
-c cookies.txt \
-d '{ "email": "ana@acme.com", "password": "…" }'
Sign out
POST/v1/admin/auth/logout
Auth: None.
Deletes the session on the server, not just the cookie.
Responses
200 OK Signed out, or there was no session.
{
"ok": true
}
Common errors (500)
{
"error": "INTERNAL_ERROR"
}
Example
curl -X POST http://127.0.0.1:3000/v1/admin/auth/logout -b cookies.txt
Who am I
GET/v1/admin/auth/me
Auth: Personal access token or dashboard session, role reader or higher.
The member behind the credential, and what the credential allows. environmentIds: null means every environment.
Responses
200 OK Found.
{
"member": {
"id": "5d1f0c2a-8b3e-4f6a-9c7d-2e1b0a9f8e7d",
"email": "ana@acme.com",
"name": "Ana",
"role": "owner",
"hasPassword": true,
"lastLoginAt": "2026-11-18T09:12:44.318Z",
"createdAt": "2026-11-17T10:00:00.000Z"
},
"principal": {
"kind": "token",
"role": "owner",
"email": "ana@acme.com",
"environmentIds": null
}
}
Common errors (401, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl http://127.0.0.1:3000/v1/admin/auth/me -H "Authorization: Bearer $FEATUREKIT_TOKEN"
Change your password
POST/v1/admin/auth/password
Auth: Personal access token or dashboard session, role reader or higher.
Ends every session, including this one, and revokes all of your access tokens: changing a password is what you do when you think someone has the old one.
Body
| Field | Type | Required | Description |
|---|---|---|---|
currentPassword | string | yes | |
newPassword | string | yes | Must meet the password policy. |
Responses
{
"ok": true
}
{
"error": "PASSWORD_REJECTED",
"message": "password must be at least 12 characters"
}
{
"error": "CREDENTIALS_REJECTED",
"message": "current password is wrong"
}
Common errors (401, 403, 400, 409, 422, 429, 413, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "CSRF_HEADER_REQUIRED",
"message": "x-featurekit-csrf is required for cookie auth"
}
{
"error": "INVALID_IDEMPOTENCY_KEY",
"message": "Idempotency-Key must be at most 200 characters of [A-Za-z0-9._:-]"
}
{
"error": "IDEMPOTENCY_IN_FLIGHT",
"message": "a request with this Idempotency-Key is still being processed"
}
{
"error": "IDEMPOTENCY_KEY_REUSED",
"message": "this Idempotency-Key was already used for a different request body"
}
{
"error": "RATE_LIMITED",
"retryAfterSeconds": 12
}
{
"error": "INVALID_JSON",
"message": "request body is not valid JSON"
}
{
"error": "PAYLOAD_TOO_LARGE",
"message": "body exceeds 4096 bytes"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -X POST http://127.0.0.1:3000/v1/admin/auth/password \
-H "Authorization: Bearer $FEATUREKIT_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "currentPassword": "…", "newPassword": "…" }'
List members
GET/v1/admin/members
Auth: Personal access token or dashboard session, role admin or higher.
Never the password hash or sessions.
Responses
200 OK Found.
{
"members": [
{
"id": "5d1f0c2a-8b3e-4f6a-9c7d-2e1b0a9f8e7d",
"email": "ana@acme.com",
"name": "Ana",
"role": "owner",
"hasPassword": true,
"lastLoginAt": "2026-11-18T09:12:44.318Z",
"createdAt": "2026-11-17T10:00:00.000Z"
},
{
"id": "6e2f1d3b-9c4f-4a7b-8d8e-3f2c1b0a9f8e",
"email": "ben@acme.com",
"name": null,
"role": "writer",
"hasPassword": true,
"lastLoginAt": null,
"createdAt": "2026-11-18T09:12:44.318Z"
}
]
}
Common errors (401, 403, 429, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "INSUFFICIENT_ROLE",
"message": "requires admin or higher"
}
{
"error": "RATE_LIMITED",
"retryAfterSeconds": 12
}
{
"error": "INTERNAL_ERROR"
}
Example
curl http://127.0.0.1:3000/v1/admin/members -H "Authorization: Bearer $FEATUREKIT_TOKEN"
Add a member
POST/v1/admin/members
Auth: Personal access token or dashboard session, role owner or higher.
A member with no password can only use access tokens, which suits a CI account.
Body
| Field | Type | Required | Description |
|---|---|---|---|
email | string | yes | |
name | string | no | |
role | string | no | owner, admin, writer (default) or reader. |
password | string | no | Must meet the password policy. |
Responses
{
"id": "6e2f1d3b-9c4f-4a7b-8d8e-3f2c1b0a9f8e",
"email": "ben@acme.com",
"name": null,
"role": "writer",
"hasPassword": true,
"lastLoginAt": null,
"createdAt": "2026-11-18T09:12:44.318Z"
}
{
"error": "INVALID_BODY",
"message": "role: Invalid option: expected one of \"owner\"|\"admin\"|\"writer\"|\"reader\""
}
{
"error": "TOKEN_SCOPED",
"message": "an environment-scoped token cannot manage members"
}
Common errors (401, 403, 400, 409, 422, 429, 413, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "CSRF_HEADER_REQUIRED",
"message": "x-featurekit-csrf is required for cookie auth"
}
{
"error": "INSUFFICIENT_ROLE",
"message": "requires owner or higher"
}
{
"error": "INVALID_IDEMPOTENCY_KEY",
"message": "Idempotency-Key must be at most 200 characters of [A-Za-z0-9._:-]"
}
{
"error": "IDEMPOTENCY_IN_FLIGHT",
"message": "a request with this Idempotency-Key is still being processed"
}
{
"error": "IDEMPOTENCY_KEY_REUSED",
"message": "this Idempotency-Key was already used for a different request body"
}
{
"error": "RATE_LIMITED",
"retryAfterSeconds": 12
}
{
"error": "INVALID_JSON",
"message": "request body is not valid JSON"
}
{
"error": "PAYLOAD_TOO_LARGE",
"message": "body exceeds 4096 bytes"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -X POST http://127.0.0.1:3000/v1/admin/members \
-H "Authorization: Bearer $FEATUREKIT_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "email": "ben@acme.com", "role": "writer", "password": "…" }'
Update a member
PATCH/v1/admin/members/{memberId}
Auth: Personal access token or dashboard session, role reader or higher.
Anyone can change their own name. Changing a role or a password, or anyone else, takes owner. A role or password change revokes the member's cached access at once.
Path parameters
| Name | Type | Description |
|---|---|---|
memberId | string | From the member list. |
Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string or null | no | |
role | string | no | |
password | string | no |
Responses
{
"id": "6e2f1d3b-9c4f-4a7b-8d8e-3f2c1b0a9f8e",
"email": "ben@acme.com",
"name": "Ben",
"role": "admin",
"hasPassword": true,
"lastLoginAt": "2026-11-18T09:12:44.318Z",
"createdAt": "2026-11-17T10:00:00.000Z"
}
{
"error": "INSUFFICIENT_ROLE",
"message": "requires owner or higher"
}
{
"error": "NOT_FOUND",
"message": "no such member"
}
{
"error": "LAST_OWNER",
"message": "this is the only owner"
}
Common errors (401, 403, 400, 409, 422, 413, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "CSRF_HEADER_REQUIRED",
"message": "x-featurekit-csrf is required for cookie auth"
}
{
"error": "INVALID_IDEMPOTENCY_KEY",
"message": "Idempotency-Key must be at most 200 characters of [A-Za-z0-9._:-]"
}
{
"error": "IDEMPOTENCY_IN_FLIGHT",
"message": "a request with this Idempotency-Key is still being processed"
}
{
"error": "IDEMPOTENCY_KEY_REUSED",
"message": "this Idempotency-Key was already used for a different request body"
}
{
"error": "INVALID_JSON",
"message": "request body is not valid JSON"
}
{
"error": "PAYLOAD_TOO_LARGE",
"message": "body exceeds 4096 bytes"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -X PATCH http://127.0.0.1:3000/v1/admin/members/6e2f1d3b-9c4f-4a7b-8d8e-3f2c1b0a9f8e \
-H "Authorization: Bearer $FEATUREKIT_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "role": "admin" }'
Remove a member
DELETE/v1/admin/members/{memberId}
Auth: Personal access token or dashboard session, role owner or higher.
Ends their sessions and deletes their tokens. Their audit history stays, without a name.
Path parameters
| Name | Type | Description |
|---|---|---|
memberId | string | From the member list. |
Responses
{
"removed": true
}
{
"error": "NOT_FOUND",
"message": "no such member"
}
{
"error": "SELF_DELETE",
"message": "you cannot remove your own account"
}
{
"error": "LAST_OWNER",
"message": "this is the only owner"
}
Common errors (401, 403, 400, 409, 422, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "CSRF_HEADER_REQUIRED",
"message": "x-featurekit-csrf is required for cookie auth"
}
{
"error": "INSUFFICIENT_ROLE",
"message": "requires owner or higher"
}
{
"error": "INVALID_IDEMPOTENCY_KEY",
"message": "Idempotency-Key must be at most 200 characters of [A-Za-z0-9._:-]"
}
{
"error": "IDEMPOTENCY_IN_FLIGHT",
"message": "a request with this Idempotency-Key is still being processed"
}
{
"error": "IDEMPOTENCY_KEY_REUSED",
"message": "this Idempotency-Key was already used for a different request body"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -X DELETE http://127.0.0.1:3000/v1/admin/members/6e2f1d3b-9c4f-4a7b-8d8e-3f2c1b0a9f8e -H "Authorization: Bearer $FEATUREKIT_TOKEN"
List your tokens
GET/v1/admin/tokens
Auth: Personal access token or dashboard session, role reader or higher.
Your own tokens. Never the secret.
Responses
200 OK Found. environmentIds: null means every environment.
{
"tokens": [
{
"id": "c0d1e2f3-a4b5-4c6d-9e7f-8a9b0c1d2e3f",
"name": "claude",
"environmentIds": [
"b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
],
"lastUsedAt": "2026-11-18T09:12:44.318Z",
"expiresAt": "2027-02-17T00:00:00.000Z"
}
]
}
Common errors (401, 429, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "RATE_LIMITED",
"retryAfterSeconds": 12
}
{
"error": "INTERNAL_ERROR"
}
Example
curl http://127.0.0.1:3000/v1/admin/tokens -H "Authorization: Bearer $FEATUREKIT_TOKEN"
Create a token
POST/v1/admin/tokens
Auth: Personal access token or dashboard session, role writer or higher.
A token can't grant more than its creator: a scoped token can only mint tokens inside its own scope, and a token made by a token can't outlive it.
Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | no | What uses it, like ci or claude. |
environmentIds | string[] | no | Environment ids (from the environment list) it may touch. Leave out for all. |
expiresAt | string | no | ISO 8601 date-time. |
Responses
{
"id": "c0d1e2f3-a4b5-4c6d-9e7f-8a9b0c1d2e3f",
"token": "fk_pat_Qm8xR3vL9pT2kW7nH4yB6cZ1"
}
{
"error": "INVALID_BODY",
"message": "environmentIds.0: Invalid UUID"
}
{
"error": "TOKEN_SCOPED",
"message": "outside your scope"
}
Common errors (401, 403, 400, 409, 422, 429, 413, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "CSRF_HEADER_REQUIRED",
"message": "x-featurekit-csrf is required for cookie auth"
}
{
"error": "INSUFFICIENT_ROLE",
"message": "requires writer or higher"
}
{
"error": "INVALID_IDEMPOTENCY_KEY",
"message": "Idempotency-Key must be at most 200 characters of [A-Za-z0-9._:-]"
}
{
"error": "IDEMPOTENCY_IN_FLIGHT",
"message": "a request with this Idempotency-Key is still being processed"
}
{
"error": "IDEMPOTENCY_KEY_REUSED",
"message": "this Idempotency-Key was already used for a different request body"
}
{
"error": "RATE_LIMITED",
"retryAfterSeconds": 12
}
{
"error": "INVALID_JSON",
"message": "request body is not valid JSON"
}
{
"error": "PAYLOAD_TOO_LARGE",
"message": "body exceeds 8192 bytes"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -X POST http://127.0.0.1:3000/v1/admin/tokens \
-H "Authorization: Bearer $FEATUREKIT_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "claude", "environmentIds": ["b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d"], "expiresAt": "2027-02-17T00:00:00Z" }'
Revoke a token
DELETE/v1/admin/tokens/{tokenId}
Auth: Personal access token or dashboard session, role reader or higher.
Path parameters
| Name | Type | Description |
|---|---|---|
tokenId | string | From your token list. |
Responses
{
"revoked": true
}
{
"error": "NOT_FOUND",
"message": "no such token"
}
Common errors (401, 403, 400, 409, 422, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "CSRF_HEADER_REQUIRED",
"message": "x-featurekit-csrf is required for cookie auth"
}
{
"error": "INVALID_IDEMPOTENCY_KEY",
"message": "Idempotency-Key must be at most 200 characters of [A-Za-z0-9._:-]"
}
{
"error": "IDEMPOTENCY_IN_FLIGHT",
"message": "a request with this Idempotency-Key is still being processed"
}
{
"error": "IDEMPOTENCY_KEY_REUSED",
"message": "this Idempotency-Key was already used for a different request body"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -X DELETE http://127.0.0.1:3000/v1/admin/tokens/c0d1e2f3-a4b5-4c6d-9e7f-8a9b0c1d2e3f -H "Authorization: Bearer $FEATUREKIT_TOKEN"