# OAuth · REST API

> OAuth2 authorization endpoints — exchange a Client ID / Client Secret for an access token, for developer and customer integrations.

HTML version: https://developers.sheetgo.com/api/auth/

[Developers](/index.md) › [REST API](/api.md) › [Authentication](/api.md#api-endpoints)

REST API · 2 endpoints

## OAuth

**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](#models), so you do not need another page to build a request. Base URL `https://api.sheetgo.com`; paths are complete, version included (`/rest/beta/…`): append them to the base URL exactly as shown; send `Authorization: Bearer sg_…`. Also in the API's own docs: <https://api.sheetgo.com/rest/reference/auth> ([Markdown](https://api.sheetgo.com/rest/reference/auth.md)).

**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: [REST API › Errors](/api.md#api-errors).

**Python recipes.** [API client helper](/examples.md#recipe-sheetgo-api).

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

##### Request body (required)

`application/json` · [`RefreshTokenRequest`](#model-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`](#model-ExchangedToken) |
| 401 | Refresh token expired, revoked or unknown | — |
| 404 | Not found | — |
| 422 | Validation Error | [`HTTPValidationError`](#model-HTTPValidationError) |

##### Example request

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

In the API's own docs: <https://api.sheetgo.com/rest/reference/auth#post-rest-auth-refresh>

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

##### Request body (required)

`application/x-www-form-urlencoded` · [`Body_auth_token_rest_auth_token_post`](#model-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`](#model-ExchangedToken) |
| 401 | Invalid code, client credentials or redirect\_uri | — |
| 404 | Not found | — |
| 422 | Validation Error | [`HTTPValidationError`](#model-HTTPValidationError) |

##### Example request

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

In the API's own docs: <https://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 the [Models](/api/models.md) page.

#### `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](/api/auth.md#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](/api/auth.md#post-rest-auth-refresh), [POST /rest/auth/token](/api/auth.md#post-rest-auth-token)

#### `HTTPValidationError`

| Field | Type |  | Description |
| --- | --- | --- | --- |
| `detail` | array of [`ValidationError`](#model-ValidationError) | optional |  |

Used by: [GET /rest/beta/workflows/](/api/workflows.md#get-rest-beta-workflows), [POST /rest/beta/workflows/](/api/workflows.md#post-rest-beta-workflows), [POST /rest/beta/workflows/run/{id}](/api/workflows.md#post-rest-beta-workflows-run-id), [GET /rest/beta/workflows/{id}](/api/workflows.md#get-rest-beta-workflows-id), [PATCH /rest/beta/workflows/{id}](/api/workflows.md#patch-rest-beta-workflows-id), [DELETE /rest/beta/workflows/{id}](/api/workflows.md#delete-rest-beta-workflows-id), [GET /rest/beta/workflows/{id}/collaborators](/api/workflows.md#get-rest-beta-workflows-id-collaborators), [POST /rest/beta/workflows/{id}/collaborators](/api/workflows.md#post-rest-beta-workflows-id-collaborators), [DELETE /rest/beta/workflows/{id}/collaborators](/api/workflows.md#delete-rest-beta-workflows-id-collaborators), [PATCH /rest/beta/workflows/{id}/collaborators/{email}](/api/workflows.md#patch-rest-beta-workflows-id-collaborators-email), [DELETE /rest/beta/workflows/{id}/collaborators/{email}](/api/workflows.md#delete-rest-beta-workflows-id-collaborators-email), [GET /rest/beta/workflows/{id}/destinations](/api/workflows.md#get-rest-beta-workflows-id-destinations), [GET /rest/beta/workflows/{id}/files](/api/workflows.md#get-rest-beta-workflows-id-files), [GET /rest/beta/workflows/{id}/general-access](/api/workflows.md#get-rest-beta-workflows-id-general-access), [PUT /rest/beta/workflows/{id}/general-access](/api/workflows.md#put-rest-beta-workflows-id-general-access), [DELETE /rest/beta/workflows/{id}/general-access](/api/workflows.md#delete-rest-beta-workflows-id-general-access), [POST /rest/beta/workflows/{id}/leave](/api/workflows.md#post-rest-beta-workflows-id-leave), [POST /rest/beta/workflows/{id}/request-access](/api/workflows.md#post-rest-beta-workflows-id-request-access), [GET /rest/beta/workflows/{id}/run](/api/workflows.md#get-rest-beta-workflows-id-run), [POST /rest/beta/workflows/{id}/run](/api/workflows.md#post-rest-beta-workflows-id-run), [GET /rest/beta/workflows/{id}/sources](/api/workflows.md#get-rest-beta-workflows-id-sources), [GET /rest/beta/automations/](/api/automations.md#get-rest-beta-automations), [POST /rest/beta/automations/run/{id}](/api/automations.md#post-rest-beta-automations-run-id), [GET /rest/beta/automations/{id}](/api/automations.md#get-rest-beta-automations-id), [DELETE /rest/beta/automations/{id}](/api/automations.md#delete-rest-beta-automations-id), [GET /rest/beta/automations/{id}/destinations](/api/automations.md#get-rest-beta-automations-id-destinations), [GET /rest/beta/automations/{id}/files](/api/automations.md#get-rest-beta-automations-id-files), [GET /rest/beta/automations/{id}/run](/api/automations.md#get-rest-beta-automations-id-run), [POST /rest/beta/automations/{id}/run](/api/automations.md#post-rest-beta-automations-id-run), [GET /rest/beta/automations/{id}/sources](/api/automations.md#get-rest-beta-automations-id-sources), [GET /rest/beta/workflows/{id}/trigger](/api/triggers.md#get-rest-beta-workflows-id-trigger), [DELETE /rest/beta/workflows/{id}/trigger](/api/triggers.md#delete-rest-beta-workflows-id-trigger), [GET /rest/beta/workflows/{id}/dashboard](/api/dashboards.md#get-rest-beta-workflows-id-dashboard), [DELETE /rest/beta/workflows/{id}/dashboard/elements/{element\_id}](/api/dashboards.md#delete-rest-beta-workflows-id-dashboard-elements-element-id), [GET /rest/beta/workflows/{id}/dashboard/elements/{element\_id}/data](/api/dashboards.md#get-rest-beta-workflows-id-dashboard-elements-element-id-data), [PUT /rest/beta/workflows/{id}/dashboard/publish](/api/dashboards.md#put-rest-beta-workflows-id-dashboard-publish), [GET /rest/beta/workflows/{workflow\_id}/forms/](/api/forms.md#get-rest-beta-workflows-workflow-id-forms), [POST /rest/beta/workflows/{workflow\_id}/forms/](/api/forms.md#post-rest-beta-workflows-workflow-id-forms), [GET /rest/beta/workflows/{workflow\_id}/forms/{form\_id}](/api/forms.md#get-rest-beta-workflows-workflow-id-forms-form-id), [PATCH /rest/beta/workflows/{workflow\_id}/forms/{form\_id}](/api/forms.md#patch-rest-beta-workflows-workflow-id-forms-form-id), [DELETE /rest/beta/workflows/{workflow\_id}/forms/{form\_id}](/api/forms.md#delete-rest-beta-workflows-workflow-id-forms-form-id), [GET /rest/beta/workflows/{workflow\_id}/forms/{form\_id}/responses](/api/forms.md#get-rest-beta-workflows-workflow-id-forms-form-id-responses), [HEAD /rest/beta/workflows/{workflow\_id}/forms/{form\_id}/responses](/api/forms.md#head-rest-beta-workflows-workflow-id-forms-form-id-responses), [GET /rest/beta/automations/{automation\_id}/webhook](/api/webhook.md#get-rest-beta-automations-automation-id-webhook), [GET /rest/beta/workflows/{workflow\_id}/webhooks](/api/webhook.md#get-rest-beta-workflows-workflow-id-webhooks), [GET /rest/beta/api-destination/{public\_id}](/api/api-destination.md#get-rest-beta-api-destination-public-id), [HEAD /rest/beta/api-destination/{public\_id}](/api/api-destination.md#head-rest-beta-api-destination-public-id), [GET /rest/beta/integrations/{provider}/options](/api/integrations.md#get-rest-beta-integrations-provider-options), [GET /rest/beta/outlook/messages](/api/outlook.md#get-rest-beta-outlook-messages), [POST /rest/beta/outlook/messages/batch](/api/outlook.md#post-rest-beta-outlook-messages-batch), [GET /rest/beta/outlook/messages/{message\_id}](/api/outlook.md#get-rest-beta-outlook-messages-message-id), [GET /rest/beta/outlook/messages/{message\_id}/attachments/{attachment\_id}](/api/outlook.md#get-rest-beta-outlook-messages-message-id-attachments-attachment-id), [POST /rest/beta/outlook/send](/api/outlook.md#post-rest-beta-outlook-send), [GET /rest/beta/gmail/messages](/api/gmail.md#get-rest-beta-gmail-messages), [POST /rest/beta/gmail/messages/batch](/api/gmail.md#post-rest-beta-gmail-messages-batch), [GET /rest/beta/gmail/messages/{message\_id}](/api/gmail.md#get-rest-beta-gmail-messages-message-id), [GET /rest/beta/gmail/messages/{message\_id}/attachments/{attachment\_id}](/api/gmail.md#get-rest-beta-gmail-messages-message-id-attachments-attachment-id), [POST /rest/beta/gmail/send](/api/gmail.md#post-rest-beta-gmail-send), [GET /rest/beta/files/{provider}](/api/files.md#get-rest-beta-files-provider), [GET /rest/beta/files/{provider}/roots](/api/files.md#get-rest-beta-files-provider-roots), [GET /rest/beta/files/{provider}/search](/api/files.md#get-rest-beta-files-provider-search), [GET /rest/beta/files/{provider}/{file\_id}](/api/files.md#get-rest-beta-files-provider-file-id), [GET /rest/beta/bigquery/projects](/api/bigquery.md#get-rest-beta-bigquery-projects), [GET /rest/beta/bigquery/projects/{project}/datasets](/api/bigquery.md#get-rest-beta-bigquery-projects-project-datasets), [GET /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables](/api/bigquery.md#get-rest-beta-bigquery-projects-project-datasets-dataset-tables), [GET /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables/{table}](/api/bigquery.md#get-rest-beta-bigquery-projects-project-datasets-dataset-tables-table), [POST /rest/beta/bigquery/projects/{project}/validate-query](/api/bigquery.md#post-rest-beta-bigquery-projects-project-validate-query), [POST /rest/auth/refresh](/api/auth.md#post-rest-auth-refresh), [POST /rest/auth/token](/api/auth.md#post-rest-auth-token)

#### `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](/api/auth.md#post-rest-auth-refresh)

#### `ValidationError`

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