auth

REST API · 2 endpoints

Complete for this group. Each operation below lists its parameters, request body, responses and errors. Every model they use is documented under Models used on this page, so you do not need another page to build a request. Base URL https://dev-api.sheetgo.com; send Authorization: Bearer sg_…. Latest version: https://dev-api.sheetgo.com/rest/reference/auth (Markdown).

Conventions for every endpoint. Lists take page (from 1) and per_page (1-100, default 50), and total counts pages, not items. Collection URLs end with /. POST …/run returns 200 when the run is queued; poll GET …/run. Google Sheets use provider: "drive"; column fields take letters ("E"). Error bodies and status codes: api.html#api-errors.

Python recipes. API client helper.

OAuth2 authorization endpoints — exchange a Client ID / Client Secret for an access token, for developer and customer integrations. For most use cases an API key generated on your Account page is simpler (see Authentication above).

Operations

POST/rest/auth/refreshCreates a new access token from a refresh token

Exchanges a refresh token for a fresh access token, so a long-running integration never has to send the user back through the authorize screen.

grant_type must be refresh_token. A token that has expired, been revoked or is unknown answers 401 — restart the authorization-code flow from the beginning.

client_id and client_secret are verified: a refresh token alone is not sufficient. A deleted or disabled application is refused.

Request body (required)

application/json · RefreshTokenRequest

Field	Type		Description
`client_id`	string	required	Your application's client id.
`client_secret`	string	required	Your application's client secret. Never expose it in a browser or mobile client.
`grant_type`	string	optional	OAuth2 grant type. Must be `refresh_token` for this endpoint. Default: `"refresh_token"`
`refresh_token`	string	required	The refresh token previously issued by `POST /rest/auth/token`.

Responses

Status	Meaning	Body
200	A new access token	`ExchangedToken`
401	Refresh token expired, revoked or unknown	—
404	Not found	—
422	Validation Error	`HTTPValidationError`

Example request

curl -s -X POST "https://dev-api.sheetgo.com/rest/auth/refresh" \
  -H "Authorization: Bearer $SHEETGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

Latest version: https://dev-api.sheetgo.com/rest/reference/auth#post-rest-auth-refresh

POST/rest/auth/tokenExchange authentication code for a access token and a refresh token

Second leg of the OAuth2 authorization-code flow: trades the one-time code your redirect URI received for an access token and a refresh token.

The body is form-encoded (application/x-www-form-urlencoded), not JSON. grant_type must be authorization_code, and redirect_uri must match the one used to obtain the code.

Codes are single-use and short-lived. Bad credentials, a reused code or a mismatched redirect URI all answer 401.

Request body (required)

application/x-www-form-urlencoded · Body_auth_token_rest_auth_token_post

Field	Type		Description
`client_id`	string	required	Your application's client id.
`client_secret`	string	required	Your application's client secret. Never expose it in a browser or mobile client.
`code`	string	required	The single-use authorization code returned to your redirect URI by the authorize step.
`grant_type`	string	required	OAuth2 grant type. Must be `authorization_code`.
`redirect_uri`	string	required	The same redirect URI that was used to obtain `code`. It must match your application's registered URI exactly.

Responses

Status	Meaning	Body
200	Access and refresh token	`ExchangedToken`
401	Invalid code, client credentials or redirect_uri	—
404	Not found	—
422	Validation Error	`HTTPValidationError`

Example request

curl -s -X POST "https://dev-api.sheetgo.com/rest/auth/token" \
  -H "Authorization: Bearer $SHEETGO_API_KEY" \
  --data-urlencode "FIELD=VALUE"

Latest version: https://dev-api.sheetgo.com/rest/reference/auth#post-rest-auth-token

Models used on this page

Every request and response model referenced above, including nested ones (5). The full catalogue is on api-models.html.

`Body_auth_token_rest_auth_token_post`

Field	Type		Description
`client_id`	string	required	Your application's client id.
`client_secret`	string	required	Your application's client secret. Never expose it in a browser or mobile client.
`code`	string	required	The single-use authorization code returned to your redirect URI by the authorize step.
`grant_type`	string	required	OAuth2 grant type. Must be `authorization_code`.
`redirect_uri`	string	required	The same redirect URI that was used to obtain `code`. It must match your application's registered URI exactly.

Used by: POST /rest/auth/token

`ExchangedToken`

The token pair returned by the OAuth2 token and refresh endpoints.

Field	Type		Description
`access_token`	string	required	Short-lived bearer token. Send it as `Authorization: Bearer <access_token>` on API calls.
`refresh_token`	string	required	Long-lived token used to obtain a new access token from `POST /rest/auth/refresh` once the access token expires. Store it securely; it is as sensitive as a password.

Used by: POST /rest/auth/refresh, POST /rest/auth/token

`HTTPValidationError`

Field	Type		Description
`detail`	array of `ValidationError`	optional

`RefreshTokenRequest`

The parameters used when refreshing a token

Field	Type		Description
`client_id`	string	required	Your application's client id.
`client_secret`	string	required	Your application's client secret. Never expose it in a browser or mobile client.
`grant_type`	string	optional	OAuth2 grant type. Must be `refresh_token` for this endpoint. Default: `"refresh_token"`
`refresh_token`	string	required	The refresh token previously issued by `POST /rest/auth/token`.

Used by: POST /rest/auth/refresh

`ValidationError`

Field	Type
`loc`	array of string or integer	required
`msg`	string	required
`type`	string	required