Skip to content

Identity API

Use these endpoints to check a token before doing anything else.

Returns the token’s user, its organization with the user’s role, and the token’s name and abilities.

Terminal window
curl https://falak.example.com/api/v1/me \
-H "Authorization: Bearer $FALAK_TOKEN" -H "Accept: application/json"
200 OK
{"data": {
"user": {"id": "01k…", "name": "Ada", "email": "[email protected]"},
"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 ["*"]

Revokes the token making the request (falak logout). Returns 204. Since v0.12.0.

falak login signs in through the panel with the RFC 8628 device authorization flow. Both endpoints take no token. Since v0.12.0.

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.

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:

{"data": {"token": "…", "user": {"id": "…", "name": "Ada", "email": "[email protected]"},
"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.

A token request returns the token’s organization only; a browser session returns every membership.

200 OK
{"data": [{"id": "01k…", "name": "Acme", "slug": "acme", "role": "owner", "current": true}]}