Identity API
Use these endpoints to check a token before doing anything else.
GET /api/v1/me
Section titled “GET /api/v1/me”Returns the token’s user, its organization with the user’s role, and the token’s name and abilities.
curl https://falak.example.com/api/v1/me \ -H "Authorization: Bearer $FALAK_TOKEN" -H "Accept: application/json"{"data": { "organization": {"id": "01k…", "name": "Acme", "slug": "acme", "role": "owner"}, "token": {"name": "cli", "abilities": ["*"]}}}| Field | Meaning |
|---|---|
organization.role |
owner, admin, developer or viewer |
token.abilities |
Permission names, or ["*"] |
DELETE /api/v1/me/token
Section titled “DELETE /api/v1/me/token”Revokes the token making the request (falak logout). Returns 204. Since v0.12.0.
Browser login (device flow)
Section titled “Browser login (device flow)”falak login signs in through the panel with the RFC 8628 device authorization flow. Both endpoints take no token. Since v0.12.0.
POST /api/v1/cli/login
Section titled “POST /api/v1/cli/login”Body {"client_name": "ada-laptop"}; limited to 10 requests a minute per address.
{"data": {"device_code": "…", "user_code": "WDJB-MJHT", "expires_in": 600, "interval": 5, "verification_uri": "https://falak.example.com/cli/authorize", "verification_uri_complete": "https://falak.example.com/cli/authorize/WDJB-MJHT"}}Keep device_code secret. Show user_code and open verification_uri_complete: the person signs in, confirms their password (and 2FA code), checks the code and approves for one of their organizations.
POST /api/v1/cli/login/token
Section titled “POST /api/v1/cli/login/token”Body {"device_code": "…"}, every interval seconds. Until approved it answers 400 with {"error": …}:
error |
Meaning |
|---|---|
authorization_pending |
Not answered yet: poll again |
slow_down |
Polling too fast: add 5 seconds to the interval |
access_denied |
Denied in the browser: stop |
expired_token |
Expired (10 minutes), already collected, or unknown: start again |
Once approved, a single 200 carries the token; a second poll gets expired_token:
"organization": {"id": "…", "name": "Acme"}}}The token has the * ability (the user’s role decides), is named CLI — <client_name>, works in the approved organization only, and expires 90 days after its last use and a year after the login at most.
GET /api/v1/organizations
Section titled “GET /api/v1/organizations”A token request returns the token’s organization only; a browser session returns every membership.
{"data": [{"id": "01k…", "name": "Acme", "slug": "acme", "role": "owner", "current": true}]}