---
updatedAt: 2026-10-16T09:41:58.000Z
agentTools:
projectIndex: https://developers.ashbyhq.com/llms.txt
---
# Authentication
Use HTTP Basic Auth to authenticate with our API. You must send your API key with every request. Put your API key as the basic auth username and leave the password blank:
```curl
curl https://api.ashbyhq.com/application.list -u API_KEY: -H "Accept: application/json; version=1" --request POST --header 'Content-Type: application/json'
```
If your API key is missing, the API will respond with a 401 status code. When the provided key is wrong or deactivated, the API will respond with a 403 status code. All three situations will return a human-readable response specific to the situation.
## API Key Endpoint Permissions
Each API key has a set of permissions that determine which endpoints it can read or write. If your API key does not have the necessary permissions to access an endpoint, the API will respond with a 403 status code and an error of `missing_endpoint_permission`.
### Table of Permissions
API permissions are organized by module. You can grant an API key read or write access to each module. The following table lists the endpoints that are covered by read and write permission for each module:
| Module | Read Endpoints | Write Endpoints |
| :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Jobs** | | |
| **Candidates** | | |
| **Projects** | | |
| **Emails** | | |
| **Sourcing** | | |
| **Interviews** | | |
| **Hiring Process** | | |
| **Organization** | | |
| **Offers** | | |
| **API Keys** | | |
| **Approvals** | | |
| **Reports** | | |
| **Notetaker** | | |
| **Audit Logs** | | |
### Confidential Job and Project Access
By default, API keys cannot access confidential job and project information. This includes job/project data, job considerations, and candidates for confidential jobs and projects. To grant an API key access to confidential job and project information, you must select the "Allow access to confidential jobs and projects?" permission in the [Ashby web app](https://app.ashbyhq.com/admin/api/credentials).
### Private Fields Access
By default, API keys cannot access information stored in private fields on candidates, except on offers. To grant an API key access to private field information on other modules, you must select the "Allow access to non-offer private fields?" permission in the [Ashby web app](https://app.ashbyhq.com/admin/api/credentials).
### Managing API Key Permissions
An Ashby Admin can manage permissions for existing API keys in the [Ashby web app](https://app.ashbyhq.com/admin/api/credentials):
### Permissions for Merge Integrations
If you access Ashby data using the [Merge ATS API](https://www.merge.dev/integrations/ashby), you will need to grant your API key the necessary permissions for Merge to access the data you need. You can find a mapping between Merge Common Models and the Ashby endpoints they use in the [Merge documentation for Ashby here](https://docs.merge.dev/integrations/ats/ashby/provider-interactions/).
## X-On-Behalf-Of Header
> The `X-On-Behalf-Of` header allows an API key to perform actions as a specific user in your organization. When this header is provided, the API request is attributed to the specified user rather than the API key's service account. This is useful when you want actions like creating notes or submitting feedback to be attributed to the actual user who initiated the action.
To use this header, send the user's Ashby ID in the `X-On-Behalf-Of` header:
```curl
curl https://api.ashbyhq.com/candidate.createNote -u API_KEY: \
-H "Accept: application/json; version=1" \
-H "Content-Type: application/json" \
-H "X-On-Behalf-Of: USER_ID" \
--request POST \
--data '{"candidateId": "...", "note": "..."}'
```
### Requirements
* The API key must have the "Allow acting on behalf of a user" permission enabled in the [Ashby web app](https://app.ashbyhq.com/admin/api/credentials).
* The `X-On-Behalf-Of` value must be a valid Ashby user ID belonging to the same organization as the API key.
* The user must be an active (non-disabled) user.
### Finding a User ID
You can find a user's Ashby ID using the [`user.search`](https://developers.ashbyhq.com/reference/usersearch) endpoint (look up by email) or the [`user.list`](https://developers.ashbyhq.com/reference/userlist) endpoint (list all users). Both return user objects that include the `id` field.