App sign-in and connected apps

What the manifest asks for

GET /api/v1/apps/{appId}/consent

What the app asks the user to approve: its name, publisher, version and scopes, from the manifest the node installed. Needs no sign-in.

Who may call it: None: anyone may call it.

Path parameters: appId.

Response (200, JSON):

Field	Type	Required	Notes
app_id	string	yes
app_name	string	yes
publisher	string	yes
scopes	array of object	yes
scopes[].description	string	yes
scopes[].id	string	yes
version	string	yes

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X GET "https://node.example.com/api/v1/apps/{appId}/consent"

Approve consent and issue tokens

POST /api/v1/apps/{appId}/grants

Approves the app for the signed-in user and issues its tokens, from the consent ticket the sign-in page gave and, for a PKCE sign-in, the code verifier.

Who may call it: Optional: the console session (its cookie, and X-CSRF-Token on writes), or none.

Path parameters: appId.

Request body (JSON):

Field	Type	Required	Notes
code_verifier	string	no
consent_ticket	string	yes

Response (200, JSON):

Field	Type	Required	Notes
access_token	string	yes
expires_in	integer	yes
refresh_token	string	yes
token_type	string	yes

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X POST "https://node.example.com/api/v1/apps/{appId}/grants" \
  -b cookies.txt -H "X-CSRF-Token: $CSRF" \
  -H "Content-Type: application/json" \
  -d '{"consent_ticket": "..."}'

Who is signed in, on which node, in which app

GET /api/v1/apps/{appId}/session

Who the app is signed in as, on which node, and the app as the node installed it.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes), an API token with a scope for this app (Authorization: Bearer oak_pat_...) or the app’s own access token (Authorization: Bearer ...).

Path parameters: appId.

Response (200, JSON):

Field	Type	Required	Notes
app	object	yes
app.id	string	yes
app.name	string	yes
app.version	string	yes
node	object	yes
node.id	string	yes
node.name	string	yes
node.url	string	yes
user	object	yes
user.id	string	yes
user.name	string	yes
user.username	string	yes

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X GET "https://node.example.com/api/v1/apps/{appId}/session" \
  -H "Authorization: Bearer $TOKEN"

My connected apps

GET /api/v1/me/grants

The apps the account has approved.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes).

Response: no body on success.

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X GET "https://node.example.com/api/v1/me/grants" \
  -b cookies.txt

Revoke a grant

DELETE /api/v1/me/grants/{id}

Revokes an app’s grant: its tokens stop working on the next request.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes).

Path parameters: id.

Response: no body on success.

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X DELETE "https://node.example.com/api/v1/me/grants/{id}" \
  -b cookies.txt -H "X-CSRF-Token: $CSRF"