> ## Documentation Index
> Fetch the complete documentation index at: https://docs.60db.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Start OAuth Sign-in

> Start Connect with Zendesk, Google Calendar, Google Drive, Google Sheets or Salesforce, and get the provider's sign-in URL

Start a **Connect with …** sign-in for a provider whose catalog entry has `oauth: true`. The response is the provider's sign-in URL. Send the user's browser there. After the user approves, the provider returns to your integrations page, and 60db stores the connection.

This endpoint is for the 60db app and other browser sign-ins. The sign-in is tied to the browser that started it by a short-lived cookie, so the same browser must open the URL. You need the `integration:write` permission (owner, admin or developer).

## How the sign-in completes

1. Open the `url` from the response in the same browser.
2. The user approves on the provider's page.
3. The provider redirects to the Redirect URL (your integrations page, see `oauth_redirect_uri` in the [catalog](https://docs.60db.ai/api-reference/agents/list-integration-catalog.md)) with `code` and `state`.
4. That page passes them to `GET /agents/integrations/oauth/callback`. 60db checks the state against the cookie (single use, 15 minutes), exchanges the code, stores the tokens encrypted, and runs the live test.
5. The browser lands back on the integrations page with `?integration_oauth=connected&integration=<id>`, or `?integration_oauth=error&reason=<reason>`, optionally with `&detail=<provider OAuth error code>`.

60db renews the sign-in automatically before it expires. Tokens and client secrets are never returned.

## Request

### Headers

**Authorization** `string` *required*

Bearer token, or the 60db app session

### Body

**provider** `string` *required*

`zendesk`, `google_calendar`, `google_drive`, `google_sheets` or `salesforce`

**name** `string`

Name of the new connection. Defaults to the provider name. A taken name gets a short suffix.

**connection\_id** `string`

An existing connection to reconnect (UUID). Its stored OAuth client is used unless `fields` gives a new one.

**fields** `object`

Field values from the catalog. Use `oauth_client_id` and `oauth_client_secret` for your own OAuth client (required unless the catalog says `oauth_default_client: true`), `subdomain` for Zendesk, and optionally `spreadsheet_id` and `sheet` (default spreadsheet and tab) for Google Sheets.

```bash theme={null}
curl -X POST https://api.60db.ai/agents/integrations/oauth/start \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google_calendar",
    "fields": { "oauth_client_id": "1234-abc.apps.googleusercontent.com", "oauth_client_secret": "GOCSPX-..." }
  }'
```

## Response

**200 OK**

```json theme={null}
{ "success": true, "data": { "url": "https://accounts.google.com/o/oauth2/v2/auth?response_type=code&client_id=...&state=...&code_challenge=..." } }
```

## Callback outcomes

| `reason` | Meaning |
| - | - |
| `denied` | The user cancelled on the provider's page |
| `expired` | The sign-in took longer than 15 minutes, or was already used |
| `state_mismatch` | The sign-in was finished in another browser than the one that started it |
| `exchange_failed` | The provider did not issue a token. Check the OAuth client ID, secret and Redirect URL. `detail` names the provider's error code, such as `invalid_client` |
| `test_failed` | Signed in, but the live test failed |

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | `VALIDATION_ERROR` | A field is missing or wrong, for example the Zendesk sub-domain, or a secret pasted into the client ID field |
| 403 | | No `integration:write` permission |
| 404 | `INTEGRATION_NOT_FOUND` | `connection_id` is not a connection of this workspace |
| 422 | `INTEGRATION_OAUTH_NOT_CONFIGURED` | The provider has no OAuth, or no OAuth client was given and the server has no default |
| 429 | `RATE_LIMITED` | Too many changes in the last minute |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.