Star
API reference

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

FieldTypeRequiredDescription
emailstringyes
passwordstringyes

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

FieldTypeRequiredDescription
currentPasswordstringyes
newPasswordstringyesMust 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

FieldTypeRequiredDescription
emailstringyes
namestringno
rolestringnoowner, admin, writer (default) or reader.
passwordstringnoMust 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

NameTypeDescription
memberIdstringFrom the member list.

Body

FieldTypeRequiredDescription
namestring or nullno
rolestringno
passwordstringno

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

NameTypeDescription
memberIdstringFrom 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

FieldTypeRequiredDescription
namestringnoWhat uses it, like ci or claude.
environmentIdsstring[]noEnvironment ids (from the environment list) it may touch. Leave out for all.
expiresAtstringnoISO 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

NameTypeDescription
tokenIdstringFrom 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"