# Gusto OAuth callback of a directory source

<div class="api-op" data-api-operation>
<div class="api-op__main">

<p class="api-endpoint"><span class="method method-get">GET</span> <code>/v1/directory_sources/oauth/gusto/callback</code></p>

The redirect URI registered on the OhAuthCat Gusto app. Consumes the state (single use, 30 minutes, bound to one environment and directory), exchanges the code with the PKCE verifier, stores the tokens sealed, reads the companies the grant reaches and saves the source (scheduling a sync) when there is exactly one. Then redirects to the start request's `return_url` with `ohauthcat_oauth` (`connected`, `choose_company` or `error`), `directory_id` and, on error, `error_code`. An expired, unused state (kept 24 hours past expiry) redirects to `return_url` with `ohauthcat_oauth=error` and `error_code=directory_source_oauth_expired`, and is used up by it. An unknown or already used state answers `directory_source_oauth_state_invalid` (400) without redirecting: an HTML page for a browser, JSON otherwise.

<dl class="api-facts"><div><dt>Scope</dt><dd><code>public</code></dd></div><div><dt>Auth</dt><dd>None</dd></div><div><dt>Since</dt><dd>1.0</dd></div></dl>

## Query parameters

<ul class="api-fields">
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">code</code> <span class="api-field__type">string</span></p>
Absent when Gusto reports an error.

<p class="api-field__chips">max length 2048</p>
</li>
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">state</code> <span class="api-field__type">string</span></p>

<p class="api-field__chips">max length 256</p>
</li>
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">error</code> <span class="api-field__type">string</span></p>
Gusto's error (RFC 6749 §4.1.2.1), e.g. `access_denied`.

<p class="api-field__chips">max length 256</p>
</li>
</ul>

## Headers

<ul class="api-fields">
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">OhAuthCat-Version</code> <span class="api-field__type">string</span></p>
Minor version; defaults to the environment's pin.
</li>
</ul>

## Responses

<ul class="api-responses">
<li class="api-response"><span class="api-status api-status--neutral">302</span> <span>Redirect to the start request's return_url.</span></li>
<li class="api-response"><span class="api-status api-status--bad">400</span> <span>`<a href="/errors/directory_source_oauth_state_invalid/">directory_source_oauth_state_invalid</a>`: the state is unknown, already used or malformed. A browser (Accept text/html) gets a short self-contained HTML page (&quot;This link can't be used&quot;) naming only the request ID; API clients get the JSON error. <span class="api-field__type">Error</span></span></li>
<li class="api-response"><span class="api-status api-status--bad">429</span> <span>Code: <a href="/errors/rate_limited/">rate_limited</a>. Retry-After is set. <span class="api-field__type">Error</span></span></li>
<li class="api-response"><span class="api-status api-status--bad">503</span> <span>Code: <a href="/errors/service_unavailable/">service_unavailable</a>. Retry-After is set; writes are paused. <span class="api-field__type">Error</span></span></li>
<li class="api-response"><span class="api-status api-status--neutral">default</span> <span>Any other error, including <a href="/errors/internal_error/">internal_error</a>. Every code is in the error catalogue. <span class="api-field__type">Error</span></span></li>
</ul>

Errors share one shape; see the [error code catalogue](/errors/).

</div>
<div class="api-op__code">

**curl**

```sh wrap
curl -X GET \
  "https://api.ohauthcat.com/v1/directory_sources/oauth/gusto/callback"
```

**Node**

```javascript wrap
const response = await fetch(
  "https://api.ohauthcat.com/v1/directory_sources/oauth/gusto/callback",
  {
    method: "GET",
  },
);
const data = await response.json();
```

**Python**

```python wrap
import os
import requests

response = requests.get(
    "https://api.ohauthcat.com/v1/directory_sources/oauth/gusto/callback",
)
data = response.json()
```

</div>
</div>
