Skip to content

Commit 51472b6

Browse files
author
Lasim
committed
feat(backend): implement OAuth token retrieval and status endpoints
1 parent 3729357 commit 51472b6

File tree

18 files changed

+1664
-20
lines changed

18 files changed

+1664
-20
lines changed

‎package-lock.json‎

Lines changed: 22 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎services/backend/api-spec.json‎

Lines changed: 337 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34001,6 +34001,343 @@
3400134001
}
3400234002
}
3400334003
},
34004+
"/api/satellites/{satelliteId}/tokens/retrieve": {
34005+
"post": {
34006+
"summary": "Retrieve decrypted OAuth tokens for MCP server spawning",
34007+
"tags": [
34008+
"Satellite OAuth"
34009+
],
34010+
"description": "Returns decrypted OAuth access and refresh tokens for a specific MCP server installation. Only accessible by authenticated satellites. Rate limited to 100 requests per minute per satellite.",
34011+
"requestBody": {
34012+
"content": {
34013+
"application/json": {
34014+
"schema": {
34015+
"type": "object",
34016+
"properties": {
34017+
"installation_id": {
34018+
"type": "string",
34019+
"minLength": 1,
34020+
"description": "MCP server installation ID"
34021+
},
34022+
"user_id": {
34023+
"type": "string",
34024+
"minLength": 1,
34025+
"description": "User ID who owns the tokens"
34026+
},
34027+
"team_id": {
34028+
"type": "string",
34029+
"minLength": 1,
34030+
"description": "Team ID for team isolation"
34031+
}
34032+
},
34033+
"required": [
34034+
"installation_id",
34035+
"user_id",
34036+
"team_id"
34037+
],
34038+
"additionalProperties": false
34039+
}
34040+
}
34041+
},
34042+
"required": true
34043+
},
34044+
"parameters": [
34045+
{
34046+
"schema": {
34047+
"type": "string"
34048+
},
34049+
"in": "path",
34050+
"name": "satelliteId",
34051+
"required": true,
34052+
"description": "Satellite ID (must match authenticated satellite)"
34053+
}
34054+
],
34055+
"security": [
34056+
{
34057+
"bearerAuth": []
34058+
}
34059+
],
34060+
"responses": {
34061+
"200": {
34062+
"description": "OAuth tokens retrieved successfully",
34063+
"content": {
34064+
"application/json": {
34065+
"schema": {
34066+
"type": "object",
34067+
"properties": {
34068+
"access_token": {
34069+
"type": "string",
34070+
"description": "Decrypted OAuth access token"
34071+
},
34072+
"refresh_token": {
34073+
"type": [
34074+
"null",
34075+
"string"
34076+
],
34077+
"description": "Decrypted OAuth refresh token (null if not available)"
34078+
},
34079+
"token_type": {
34080+
"type": "string",
34081+
"description": "Token type (usually \"Bearer\")"
34082+
},
34083+
"expires_at": {
34084+
"type": [
34085+
"null",
34086+
"string"
34087+
],
34088+
"format": "date-time",
34089+
"description": "Token expiration timestamp (ISO 8601 format)"
34090+
},
34091+
"scope": {
34092+
"type": [
34093+
"null",
34094+
"string"
34095+
],
34096+
"description": "OAuth scopes granted to the token"
34097+
}
34098+
},
34099+
"required": [
34100+
"access_token",
34101+
"token_type"
34102+
],
34103+
"description": "OAuth tokens retrieved successfully"
34104+
}
34105+
}
34106+
}
34107+
},
34108+
"403": {
34109+
"description": "Forbidden - Satellite does not have access to this team",
34110+
"content": {
34111+
"application/json": {
34112+
"schema": {
34113+
"type": "object",
34114+
"properties": {
34115+
"success": {
34116+
"type": "boolean",
34117+
"default": false,
34118+
"description": "Indicates failure"
34119+
},
34120+
"error": {
34121+
"type": "string",
34122+
"description": "Error message describing what went wrong"
34123+
}
34124+
},
34125+
"required": [
34126+
"success",
34127+
"error"
34128+
],
34129+
"description": "Forbidden - Satellite does not have access to this team"
34130+
}
34131+
}
34132+
}
34133+
},
34134+
"404": {
34135+
"description": "Not Found - No OAuth tokens found for this installation",
34136+
"content": {
34137+
"application/json": {
34138+
"schema": {
34139+
"type": "object",
34140+
"properties": {
34141+
"success": {
34142+
"type": "boolean",
34143+
"default": false,
34144+
"description": "Indicates failure"
34145+
},
34146+
"error": {
34147+
"type": "string",
34148+
"description": "Error message describing what went wrong"
34149+
}
34150+
},
34151+
"required": [
34152+
"success",
34153+
"error"
34154+
],
34155+
"description": "Not Found - No OAuth tokens found for this installation"
34156+
}
34157+
}
34158+
}
34159+
},
34160+
"500": {
34161+
"description": "Internal Server Error - Failed to retrieve or decrypt tokens",
34162+
"content": {
34163+
"application/json": {
34164+
"schema": {
34165+
"type": "object",
34166+
"properties": {
34167+
"success": {
34168+
"type": "boolean",
34169+
"default": false,
34170+
"description": "Indicates failure"
34171+
},
34172+
"error": {
34173+
"type": "string",
34174+
"description": "Error message describing what went wrong"
34175+
}
34176+
},
34177+
"required": [
34178+
"success",
34179+
"error"
34180+
],
34181+
"description": "Internal Server Error - Failed to retrieve or decrypt tokens"
34182+
}
34183+
}
34184+
}
34185+
}
34186+
}
34187+
}
34188+
},
34189+
"/api/satellites/{satelliteId}/tokens/status": {
34190+
"post": {
34191+
"summary": "Check OAuth token status without decryption",
34192+
"tags": [
34193+
"Satellite OAuth"
34194+
],
34195+
"description": "Returns token metadata (existence, expiration, refresh capability) without decrypting the tokens. Useful for satellites to check token status before attempting retrieval.",
34196+
"requestBody": {
34197+
"content": {
34198+
"application/json": {
34199+
"schema": {
34200+
"type": "object",
34201+
"properties": {
34202+
"installation_id": {
34203+
"type": "string",
34204+
"minLength": 1,
34205+
"description": "MCP server installation ID"
34206+
},
34207+
"user_id": {
34208+
"type": "string",
34209+
"minLength": 1,
34210+
"description": "User ID who owns the tokens"
34211+
},
34212+
"team_id": {
34213+
"type": "string",
34214+
"minLength": 1,
34215+
"description": "Team ID for team isolation"
34216+
}
34217+
},
34218+
"required": [
34219+
"installation_id",
34220+
"user_id",
34221+
"team_id"
34222+
],
34223+
"additionalProperties": false
34224+
}
34225+
}
34226+
},
34227+
"required": true
34228+
},
34229+
"parameters": [
34230+
{
34231+
"schema": {
34232+
"type": "string"
34233+
},
34234+
"in": "path",
34235+
"name": "satelliteId",
34236+
"required": true,
34237+
"description": "Satellite ID (must match authenticated satellite)"
34238+
}
34239+
],
34240+
"security": [
34241+
{
34242+
"bearerAuth": []
34243+
}
34244+
],
34245+
"responses": {
34246+
"200": {
34247+
"description": "Token status retrieved successfully",
34248+
"content": {
34249+
"application/json": {
34250+
"schema": {
34251+
"type": "object",
34252+
"properties": {
34253+
"exists": {
34254+
"type": "boolean",
34255+
"description": "Whether tokens exist for this installation"
34256+
},
34257+
"expired": {
34258+
"type": [
34259+
"null",
34260+
"boolean"
34261+
],
34262+
"description": "Whether the token is expired (null if no expiration time)"
34263+
},
34264+
"expires_at": {
34265+
"type": [
34266+
"null",
34267+
"string"
34268+
],
34269+
"format": "date-time",
34270+
"description": "Token expiration timestamp (ISO 8601 format)"
34271+
},
34272+
"can_refresh": {
34273+
"type": "boolean",
34274+
"description": "Whether the token can be refreshed (has refresh_token)"
34275+
}
34276+
},
34277+
"required": [
34278+
"exists",
34279+
"can_refresh"
34280+
],
34281+
"description": "Token status retrieved successfully"
34282+
}
34283+
}
34284+
}
34285+
},
34286+
"403": {
34287+
"description": "Forbidden - Satellite does not have access to this team",
34288+
"content": {
34289+
"application/json": {
34290+
"schema": {
34291+
"type": "object",
34292+
"properties": {
34293+
"success": {
34294+
"type": "boolean",
34295+
"default": false,
34296+
"description": "Indicates failure"
34297+
},
34298+
"error": {
34299+
"type": "string",
34300+
"description": "Error message describing what went wrong"
34301+
}
34302+
},
34303+
"required": [
34304+
"success",
34305+
"error"
34306+
],
34307+
"description": "Forbidden - Satellite does not have access to this team"
34308+
}
34309+
}
34310+
}
34311+
},
34312+
"500": {
34313+
"description": "Internal Server Error - Failed to check token status",
34314+
"content": {
34315+
"application/json": {
34316+
"schema": {
34317+
"type": "object",
34318+
"properties": {
34319+
"success": {
34320+
"type": "boolean",
34321+
"default": false,
34322+
"description": "Indicates failure"
34323+
},
34324+
"error": {
34325+
"type": "string",
34326+
"description": "Error message describing what went wrong"
34327+
}
34328+
},
34329+
"required": [
34330+
"success",
34331+
"error"
34332+
],
34333+
"description": "Internal Server Error - Failed to check token status"
34334+
}
34335+
}
34336+
}
34337+
}
34338+
}
34339+
}
34340+
},
3400434341
"/api/auth/email/register": {
3400534342
"post": {
3400634343
"summary": "User registration via email",

0 commit comments

Comments
 (0)