--- title: "How to connect Ashby to Kendor" description: "Create an Ashby API key with the permissions Kendor lists, paste it under Integrations, and Kendor sets up the webhook and its fields where the key allows." updated: 2026-10-06 canonical: https://kendor.io/docs/ashby/connect-ashby --- # How to connect Ashby to Kendor You connect Ashby with one API key. Create the key in Ashby, paste it into **Integrations → Ashby** in Kendor, and Kendor checks its permissions, registers the webhook and creates its fields on the application, as far as the key allows. A checklist then shows what's done and what, if anything, is left to do by hand in Ashby. > **Before you start** > > - Your organization is on the Enterprise plan, which includes the Ashby integration. > - You're an **Owner** in Kendor. Editors and Viewers see the Ashby card as **Only owners can manage Ashby.** > - You can create API keys in Ashby's admin settings. ## Create an API key in Ashby In Ashby, open **Admin → API keys** and create a key for Kendor. Kendor lists the permissions it needs on the Ashby page under **1 · Create an API key in Ashby**. ### Required | Permission in Kendor | Ashby scope | What Kendor uses it for | |---|---|---| | **Read API keys** | `apiKeys:read` | Checks which permissions the key has. | | **Read jobs** | `jobs:read` | Lists your jobs when you set up stage rules. | | **Read interviews** | `interviews:read` | Reads each job's interview plan and its stages. | | **Read hiring process metadata** | `hiringProcessMetadata:read` | Reads stages and application fields. | | **Write candidates** | `candidates:write` | Writes the Kendor fields and notes. | ### So Kendor can set itself up | Permission in Kendor | Ashby scope | What Kendor uses it for | |---|---|---| | **Write API keys** | `apiKeys:write` | Registers the webhook for you. | | **Write hiring process metadata** | `hiringProcessMetadata:write` | Creates the five Kendor fields for you. | These two are optional. Without them you add the webhook and the five fields in Ashby yourself, and Kendor shows you exactly what to enter. ## Paste the key into Kendor 1. Open **Integrations** in the sidebar, under **Organization**. 2. On the **Ashby** card in **Applicant tracking**, choose **Connect**. 3. Under **2 · Paste your Ashby API key**, paste the key into **Ashby API key** and choose **Connect**. Kendor asks Ashby which permissions the key has, then registers the webhook and finds or creates its fields. If Ashby refuses the key, the reason appears under the field, for example **Ashby rejected the API key**. The key is stored encrypted. Afterwards Kendor only shows its last four characters: **Connected with the key ending 1234**. ## Check the setup list The **Setup** section has three rows. A tick means the row is done. - **Key permissions**: every required permission is on the key. If any are missing, Kendor names them. Add them to the key in Ashby, then choose **Check again**. - **Webhook**: Ashby tells Kendor when an application changes stage. - **Kendor fields on applications**: the five fields `Kendor status`, `Kendor result`, `Kendor score`, `Kendor review` and `Kendor decision` exist on Application in Ashby. The status at the top reads **Connected** when everything is in place, and **Needs attention** when something isn't. ### Add the webhook by hand If the key can't write API keys, the **Webhook** row shows a **Webhook URL** and a **Secret token** to copy. In Ashby, open **Admin → Webhooks** and add a webhook of type **Candidate stage change** with that URL and secret. Use **Show secret** to see the full token. Each organization has its own webhook URL and secret. Ashby signs every request with the secret, and Kendor rejects any request whose signature doesn't match. ### Create the fields by hand If the key can't write hiring process metadata, create the missing fields in Ashby under **Admin → Custom fields**, on **Application**, with these exact names and types: | Field name | Type | |---|---| | `Kendor status` | String | | `Kendor result` | String | | `Kendor score` | Number | | `Kendor review` | URL | | `Kendor decision` | String | Kendor finds them by name, ignoring case. Choose **Check again** once they exist. Fields that are missing are simply skipped when Kendor writes results. > **Tip.** **Check again** re-reads the key's permissions and redoes any setup the key now allows. Use it whenever you change the key's permissions in Ashby. ## Replace or disconnect the key - **Replace key** swaps in a new key with the same permissions. The old key stops being used at once. The webhook URL and secret stay the same, so a webhook you added by hand keeps working. - **Disconnect** removes the key, your stage rules and the webhook Kendor registered, and Kendor stops writing to Ashby. A webhook you added by hand stays in Ashby until you delete it there. Invites already sent stay valid. If you connect again after disconnecting, Kendor issues a new webhook URL and secret, so update any webhook you added by hand. Next, [choose which stages send a screen](/docs/ashby/stage-triggers).