Chosen Help

reference

API keys

An API key lets a program talk to Chosen on your behalf — a CRM sync, a custom dashboard, or an AI assistant connecting over MCP. This page is how to create one, what to do with it, and how access is scoped.

What an API key is for

A key authenticates a request as coming from your organization. Anything you'd do in the app, a key with the right permissions can do over the API. Keys are also how you connect Chosen to an MCP client like Claude Desktop.

Every key carries a role — the same Owner / Admin / Viewer roles, or a custom one — and the key can only do what that role allows. A key isn't all-or-nothing access; it's exactly the access of the role you pick.

Creating a key

Managing API keys requires the api_keys:manage permission, which Owners and Admins have. Viewers don't.

  1. Open API key settings in Chosen and choose to create a key.
  2. Give it a name. A label like "Internal CRM sync" — it's how you'll recognize the key later in the list. Pick something specific; "test" tells you nothing six months on.
  3. Pick a role. This scopes what the key can do. Choose the most restrictive role that still lets the integration work — a key for a read-only dashboard should carry a read-only role.
  4. Create the key. The full key is shown once, on this screen.

What you can and can't see later

Every key starts with cho_. After creation, the key list shows only a short prefix — the first several characters — never the full value. That prefix is enough to tell two keys apart in the list; it is not enough for anyone to use the key.

The list also shows each key's name, its role, who created it, and when it was last used. The last-used time is the quick way to spot a key that no integration is actually calling anymore.

Per-key permissions and least privilege

A key never has more access than the role you assigned it — and you can't grant a key more permissions than you hold yourself. An Admin can't mint an Owner-level key. Chosen only offers you roles you're allowed to grant.

This is deliberate. A key is a credential that can leak — committed to a repo, pasted in a log. A leaked read-only key is a smaller problem than a leaked key that can delete jobs. Give each integration its own key, scoped to just what it needs, so you can revoke one without disturbing the others.

Revoking a key

Revoke a key the moment it's no longer needed, or immediately if you suspect it leaked. Revoking is instant and final — the key stops working right away and can't be reactivated. Revoking one key doesn't touch any other, which is the whole reason to give each integration its own.

The public developer API

This page covers keys created and managed inside the Chosen app. The public developer API — the full endpoint reference, request and response shapes, and an interactive console — lives separately at developers.chosenhq.com. The keys you create here are what you authenticate those API calls with: send the key as a Bearer token. For embedding jobs or pulling careers data, see embed and API.