# auth

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).

Base URL: `https://dev-api.sheetgo.com`. Start page: https://dev-api.sheetgo.com/rest/reference.md

This page documents every endpoint of the group. Request and response shapes link to model pages; fetch the model pages an endpoint links before building a body.

Guide: [Rate Limiting](https://dev-api.sheetgo.com/rest/guides/rate-limiting.md)

Every endpoint is rate limited; see the guide [Rate Limiting](https://dev-api.sheetgo.com/rest/guides/rate-limiting.md).

<a id="post-rest-auth-token"></a>
## POST /rest/auth/token

**Exchange 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**.

Authentication: see the start page.

**Request body**

Content type `application/x-www-form-urlencoded`. Required.

Body: [Body_auth_token_rest_auth_token_post](https://dev-api.sheetgo.com/rest/reference/models/Body_auth_token_rest_auth_token_post.md)

**Responses**

- `200` Access and refresh token. Schema: [ExchangedToken](https://dev-api.sheetgo.com/rest/reference/models/ExchangedToken.md)
- `404` Not found
- `401` Invalid code, client credentials or redirect_uri
- `422` Validation Error. Schema: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [Body_auth_token_rest_auth_token_post](https://dev-api.sheetgo.com/rest/reference/models/Body_auth_token_rest_auth_token_post.md), [ExchangedToken](https://dev-api.sheetgo.com/rest/reference/models/ExchangedToken.md), [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md).

<a id="post-rest-auth-refresh"></a>
## POST /rest/auth/refresh

**Creates 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.

Authentication: see the start page.

**Request body**

Content type `application/json`. Required.

Body: [RefreshTokenRequest](https://dev-api.sheetgo.com/rest/reference/models/RefreshTokenRequest.md)

**Responses**

- `200` A new access token. Schema: [ExchangedToken](https://dev-api.sheetgo.com/rest/reference/models/ExchangedToken.md)
- `404` Not found
- `401` Refresh token expired, revoked or unknown
- `422` Validation Error. Schema: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [ExchangedToken](https://dev-api.sheetgo.com/rest/reference/models/ExchangedToken.md), [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md), [RefreshTokenRequest](https://dev-api.sheetgo.com/rest/reference/models/RefreshTokenRequest.md).

---

More: start page https://dev-api.sheetgo.com/rest/reference.md, everything in one file https://dev-api.sheetgo.com/rest/llms-full.txt, OpenAPI https://dev-api.sheetgo.com/rest/openapi.json.