# BambooHR 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/bamboohr/callback</code></p>

The redirect URI registered on the OhAuthCat BambooHR apps. Consumes the state (single use, 30 minutes, bound to one environment and directory), exchanges the code on the company's BambooHR domain with the client secret, stores the tokens sealed, checks that the grant carries offline_access and that the employee list can be read, then saves the source (scheduling a sync). Redirects to the start request's `return_url` with `ohauthcat_oauth` (`connected` or `error`), `directory_id` and, on error, `error_code` (`directory_source_scope_missing` names a scope the app lacks). 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 BambooHR 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>
BambooHR'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/bamboohr/callback"
```

**Node**

```javascript wrap
const response = await fetch(
  "https://api.ohauthcat.com/v1/directory_sources/oauth/bamboohr/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/bamboohr/callback",
)
data = response.json()
```

</div>
</div>
