# Ashby

Connect Ashby so Suger AI can work with your candidates, applications, and job postings.

---

## Overview

[Ashby](https://www.ashbyhq.com) is an applicant tracking and recruiting platform covering sourcing, interviewing, and hiring analytics. Connecting it lets the Suger AI agent read and update your recruiting pipeline — candidates, applications, interviews, and job postings — from a Suger workflow or chat.

### Org-Level vs User-Level

> **Org-Level**: Supported. One Ashby API key serves the whole organization.
>
> **User-Level**: Not applicable. Ashby authenticates with an API key only — it has no OAuth flow of any kind — so there is nothing an individual user could sign in to. Every Suger user in your organization shares the org connection.

### How the connection works

Ashby authenticates with HTTP Basic, where the API key *is* the username and the password is empty. Suger stores the key and builds that header for you, so there is only one field to fill in.

```d2
shape: sequence_diagram
admin: "Your Suger admin"
suger: "Suger"
ashby: "Ashby"
agent: "Suger AI agent"
admin -> suger: "Paste the Ashby API key"
suger -> ashby: "Check the key before saving the connection"
ashby -> suger: "Accepted — connection stored" { style.stroke-dash: 4 }
rejected: "if the key is wrong or revoked" {
  ashby -> suger: "Rejected — the connect fails here, not at the first tool call" { style.stroke-dash: 4 }
}
agent -> suger: "Run an Ashby tool"
suger -> ashby: "HTTP Basic — the key as the username, blank password"
ashby -> agent: "Candidates, applications, interviews, postings" { style.stroke-dash: 4 }
```

## Create Integration (Org-Level)

### Prerequisites

- An Ashby account on a plan that includes API access.
- Permission to create an API key in Ashby (**Admin** settings).
- The Suger **Admin** role — connecting, disconnecting, and running an integration's actions are all admin-only in Suger.

### Authenticate by API key

1. In Ashby, go to **Settings → Integrations → API** and generate a new API key. Copy it — Ashby shows it once.
2. Grant the key the module permissions you want Suger to have. Ashby scopes API keys per module (Candidates, Jobs, Interviews, and so on), so a key missing a module makes every tool for that module fail. Grant read access at minimum, plus write access for anything you want the agent to change.
3. In the Suger console, open [Settings → Integrations](https://console.suger.io/settings?tab=integrations) and click **Connect** on **Ashby**.
4. Paste the key into the single **API Key** field and save.

Paste the raw key, not a base64 string — Suger builds the Basic header itself. There is no separate username or password to supply.

:::info
Suger checks the key against Ashby rather than storing it blind — Ashby is one of the few connectors that offers an endpoint for this. A wrong or revoked key is reported as an error instead of sitting in a connection that looks healthy and fails on its first tool call. The check confirms the key is valid; it cannot confirm you granted it every module the tools you plan to use will need.
:::

<!-- screenshot needed: the "Connect to Ashby" dialog showing its single API Key field — BLOCKED: the Ashby connector is provisioned by the deploy-time migration, so the dialog cannot be reached in a local dev environment on this branch -->

## Suger AI Tools

When Ashby is connected, the Suger AI agent can work your recruiting pipeline through Suger's built-in tools (23 actions).

> **Org-level**: All tools run under the org API key, so what the agent can see and change is exactly what that key's module permissions allow.

| Capability | What the agent can do |
|------------|-----------------------|
| **Candidates** | Create, read, update, and list candidates (e.g. `create-candidate`, `update-candidate`, `list-candidates`) |
| **Applications** | Create, read, update, and list applications, and move one between stages or sources (e.g. `change-application-stage`, `change-application-source`) |
| **Jobs & postings** | Read and list jobs and their public postings (e.g. `get-job`, `list-job-postings`) |
| **Interviews** | Read and list scheduled interviews (e.g. `get-interview`, `list-interviews`) |
| **Notes** | Add notes to a candidate record (`create-note`) |
| **Org data** | Read and list departments, sources, and users (e.g. `list-departments`, `list-sources`, `list-users`) |

:::tip
Open the integration from **Settings → Integrations** to see the exact tool list for your connection on its **Actions** tab, and to try a call on the **Playground** tab. The Playground pre-fills only the inputs an action *requires* — add optional ones yourself when you need them.
:::

## Edit Integration

Editing is not supported. To rotate the key or point Suger at a different Ashby account, delete the integration and create it again.

## Delete Integration

Click the 🗑️ button next to **Ashby** in the **Integrations** list. The stored key is destroyed with the integration record. Any Suger workflow or agent that depended on Ashby tools stops working immediately. Revoke the key in Ashby too if you want to cut access from that side.