A recruiting assistant can draft a useful candidate summary and still have far too much access to your ATS. The risk often starts during setup. Someone enables every API permission to make a test pass, then leaves that key attached to the production workflow. Before connecting AI to Ashby, define what the workflow may read, what it may change and who owns each exception.
This guide covers the permission boundary for an integration. It does not assume Ashby supplies a ready-made AI approval process. Recruiter review, endpoint restrictions and release controls described below are engineering recommendations for the application you build around the API.
Start with the task, then list the endpoints
Write a concrete task such as preparing a candidate briefing for an assigned recruiter. Break it into reads and actions. Reading candidate details, reading application history and creating a note are different operations. A workflow that only prepares a briefing does not automatically need permission to change application stages or submit feedback.
Build a small access register before creating the key. Record the business purpose, endpoint, module permission, data returned and expected output. Include the person who can approve an expansion. This gives the admin a decision to review instead of a broad request for ATS access.
| Workflow need | Ashby permission boundary | Application control to add |
|---|---|---|
| Read candidate and application details | Candidates read includes candidate.info and application.info | Limit retrieval to authorized records and required fields |
| Add an approved candidate note | Candidates write includes candidate.createNote | Allow only the approved note operation |
| Read recent email messages | Emails read includes candidate.getRecentEmailMessages | Decide whether message content is necessary |
| Read offer information | Offers read includes offer.info and offer.list | Keep compensation out of unrelated workflows |
| Run an attributed user action | Separate on-behalf-of permission and user header | Map the signed-in person to a verified Ashby user |
Create a dedicated key with deliberate scope
An Organization Admin creates API keys in Admin, Integrations, API Credentials. Ashby asks for a name and version, with an optional integration partner. New keys have no endpoint permissions by default. The admin selects module read or write access, reviews Other Permissions and saves the configuration.
Use a descriptive key name tied to the workflow and environment. Keep the secret in a server-side secret store, not in the model context, browser code, candidate notes or application logs. Ashby says the key cannot be viewed or copied again after the setup wizard closes. Arrange secure storage during setup rather than asking an operator to paste it into a chat later.
Ashby authenticates API requests through HTTP Basic Auth with the key as the username and an empty password. Treat that as an integration implementation detail. Recruiters should use your application without handling or seeing the underlying key.
Separate module permissions from business permissions
Module scope does not mean one business action. Ashby's Candidates write permission covers multiple endpoints, including candidate updates, note creation, application changes and anonymization. If the approved workflow only writes a reviewed note, granting the module is not enough to express that narrower policy.
Bind the target record and operation to the review decision. If a recruiter approves a note for one application, do not reuse that approval for a different candidate or a later rewritten note. Store the approved payload or a version reference so the write matches what the recruiter actually reviewed.
Review confidential jobs and private fields separately
By default, API keys cannot access confidential job and project information. Ashby says that restriction includes the job or project data, job considerations and candidates for confidential jobs and projects. A missing result can therefore be a correct access outcome, not evidence that the integration is broken.
Non-offer private fields also require separate permission. The documented default restriction has an exception for offers, so do not describe the private-field checkbox as a blanket block on every sensitive value. Inspect which modules the key can read and what the actual endpoint returns.
Use approved test fixtures for ordinary, confidential and private-field scenarios. Confirm that the application handles unavailable information without inventing a summary or silently switching to a more privileged key. A briefing can state that information was unavailable and send the case to the right operator.
Make recruiter attribution explicit
Ashby supports the X-On-Behalf-Of header for API actions attributed to a specific user rather than the key's service account. The key must have permission to act on behalf of a user. The user ID must belong to the same organization and the user must be active.
Map that identity from the authenticated application session through a controlled lookup. Do not let an AI-generated name or caller-supplied user ID decide attribution. If no verified mapping exists, stop the attributed action and ask an operator to resolve the configuration. Keep the initiator, reviewer and API actor distinct in your own audit record.
Test denied operations before enabling writes
- Confirm that the required read succeeds on an approved record.
- Confirm that an unnecessary endpoint is blocked by the application even if module scope could permit it.
- Test confidential information and private-field exclusions.
- Attempt a write without a matching review decision and verify that nothing changes.
- Test a disabled or mismatched delegated user in a controlled environment.
- Disable the integration key and confirm that the workflow stops cleanly.
Ashby documents HTTP 401 for a missing key and HTTP 403 for a wrong or deactivated key. A missing endpoint permission also returns 403, with the missing_endpoint_permission error. Classify the response before deciding what to fix. Repeated retries will not repair an access policy, and automatically adding permissions hides the original problem.
Common setup mistakes
Avoid sharing one broadly privileged key across unrelated workflows. Do not log full candidate payloads merely to debug access errors. Do not treat an empty result as permission to query every candidate. Keep field selection and retention decisions close to the task, especially when data leaves the ATS for model processing.
Review access when a workflow changes, its owner leaves or the application moves environments. Ashby lets admins edit permissions and disable keys. Record those changes in the integration register and rerun the relevant denial tests. The broader recruiting tool stack guide helps define which system owns each handoff.
How Remqa can help
Remqa builds AI agents for recruiting teams around specific tasks and operating boundaries. For an Ashby integration, that work can include endpoint mapping, permission review, controlled writes and failure handling. Bring one workflow and the records it needs to a call. Start with the smallest useful scope, then expand only when the next task justifies the access.