API ReferenceAuth

Finish social sign-in

The provider callback redirects the browser back with a two-minute single-use hand-off code — never a JWT, which in a URL would land in browser history, referrer headers and proxy logs. This trades that code for the real session, and only the app it was minted for may redeem it.

POST
/{appUid}/auth/oauth/exchange

Path Parameters

appUid*string

Your app's unique id. Find it in the console under the app's Settings, or in the URL of any app page.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/497f6eca-6276-4993-bfeb-53cbbbba6f08/auth/oauth/exchange" \  -H "Content-Type: application/json" \  -d '{    "code": "stringstringstringstringstringst"  }'
{  "uid": "string",  "email": "user@example.com",  "fname": "string",  "lname": "string",  "status": "string",  "auth": {    "accessToken": "string",    "refreshToken": "string",    "activeOrgUid": "string"  },  "orgUid": "string",  "org": {    "uid": "string",    "name": "string"  }}

Start social sign-in

Mints a single-use `state` and returns the provider's authorize URL for the browser to navigate to. Returns JSON rather than a 302 because the caller is an XHR — a redirect would be followed by the fetch, not the window.

Refresh a session

Trades the refresh token for a new access token AND a new refresh token. Refresh tokens are SINGLE-USE: the one you send stops working once exchanged, so always store the pair you get back. Presenting a refresh token that has already been exchanged ends the whole session (`SESSION_ENDED`, reason `reused`) — the server reads it as a stolen token. The one exception is a narrow grace window just after an exchange, so two tabs refreshing at the same moment both receive the same current pair; coordinate refreshes anyway. Pass `activeOrgUid` to switch the session into another organization you are an accepted member of. An `Authorization` header on this request is ignored.