Token Routes - Toolshed

Vend access token

POST /api/tokens/vend

Retrieves a usable access token for a user’s connected provider. Handles automatic refresh when tokens are expired.

{
  "userId": "user-123",
  "provider": "github"
}

Field	Type	Required	Description
`userId`	`string`	Yes	The user requesting the token
`provider`	`string`	Yes	The OAuth provider to vend a token for

{
  "accessToken": "gho_xxxxxxxxxxxx",
  "expiresAt": "2025-01-15T12:00:00Z",
  "refreshed": false
}

Field	Type	Description
`accessToken`	`string`	The usable access token
`expiresAt`	`string`	ISO 8601 expiry time (if known)
`refreshed`	`boolean`	Whether the token was refreshed during this request

Provider not linked (404):

{
  "error": "Provider not linked",
  "code": "NOT_LINKED"
}

Token expired with no refresh token (401):

{
  "error": "Token expired",
  "code": "TOKEN_EXPIRED"
}

Token revoked by user (401):

{
  "error": "Token revoked",
  "code": "TOKEN_REVOKED"
}

Refresh failed (502):

{
  "error": "Token refresh failed",
  "code": "REFRESH_FAILED"
}

Looks up encrypted tokens for the user + provider
Decrypts the access token
If expired and a refresh token exists, attempts refresh
If refresh fails with invalid_grant, cleans up stored tokens and returns TOKEN_REVOKED
Returns the usable access token