> ## Documentation Index
> Fetch the complete documentation index at: https://docs.canary.effectiveai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up an agent

> Sign an agent in through your browser so it gets its own API key, with no key to copy or paste.

Paste this into your agent, such as Claude Code:

```text Prompt theme={null}
Set up Effective for me. Read https://docs.canary.effectiveai.app/getting-started/agent-setup.md and follow it.
```

The agent asks for your workspace, runs a short script and shows you a link with a code. Open the
link, check that the page shows the same code, and select **Approve**. The agent then has its own
API key with your access. The key lasts 90 days, and you can revoke it on the **API Keys** page at
any time.

## Instructions for the agent

These rules apply however you complete the setup:

* Never print, echo or log the API key, and never paste it into the conversation.
* Save the key only in the credentials file, readable only by the current user.
* Only send requests to `https://api.canary.effectiveai.app`.
* Always show the user the link and the code, then wait for them to approve.
* If the user denies the request or it expires, say so and stop. Start again only if the user asks.

### 1. Find the workspace

Ask the user for their workspace unless they already gave it. It is the first part of the address
they open Effective at: `acme` for `acme.effectiveai.app`.

### 2. Run the setup script

The script starts the sign-in, prints the link and code, and waits up to 10 minutes for the user to
approve. Show the user the link and code as soon as they appear. If your tool stops long-running
commands, run the script in the background and read its output.

On macOS, Linux, WSL or Git Bash (needs bash and curl):

```bash theme={null}
curl --fail --output effective-setup.sh https://api.canary.effectiveai.app/api/v2/device-authorizations/setup.sh
EFFECTIVE_CLIENT_NAME="Claude Code" bash effective-setup.sh acme
```

On Windows PowerShell:

```powershell theme={null}
Invoke-WebRequest -UseBasicParsing https://api.canary.effectiveai.app/api/v2/device-authorizations/setup.ps1 -OutFile effective-setup.ps1
$env:EFFECTIVE_CLIENT_NAME = 'Claude Code'
powershell -ExecutionPolicy Bypass -File effective-setup.ps1 acme
```

Set `EFFECTIVE_CLIENT_NAME` to your own name. The user sees it on the approval page, and it becomes
the key's name. While it waits, the script prints:

```text theme={null}
Open this link to approve access to Effective:

  https://acme.effectiveai.app/device?code=BCDF-GHJK

Check that the page shows the code BCDF-GHJK, then select Approve.
Waiting for approval. The link expires in 10 minutes.
```

After approval it prints only the signed-in identity and where it saved the key:

```text theme={null}
Signed in as alex@example.com in workspace acme.
Saved the API key to /Users/alex/.config/effective/credentials. It expires 2027-01-14T20:28:50.924Z.
```

The script exits with an error and saves nothing if the user denies the request or the link
expires.

### 3. Use the key

Read the key from the credentials file into `EFFECTIVE_API_KEY` in the command that needs it:

```bash theme={null}
export EFFECTIVE_API_KEY="$(cat ~/.config/effective/credentials)"
```

On Windows, the file is `%APPDATA%\effective\credentials`:

```powershell theme={null}
$env:EFFECTIVE_API_KEY = Get-Content -Raw "$env:APPDATA\effective\credentials"
```

Then confirm the identity with `GET /users/me` and
[find an insurance product](/getting-started/quickstart#find-an-insurance-product).
Run the setup again when the key expires or the user revokes it.

## Without the scripts

If neither script can run in your environment, make the same two calls yourself. Neither needs an
API key.

Start the sign-in:

```bash theme={null}
curl --request POST \
  --url "https://api.canary.effectiveai.app/api/v2/device-authorizations" \
  --header "Content-Type: application/json" \
  --data '{"clientName": "Claude Code", "workspace": "acme"}'
```

```json Response theme={null}
{
  "deviceCode": "x1E7mH4cQk0p...",
  "userCode": "BCDF-GHJK",
  "verificationUri": "https://acme.effectiveai.app/device",
  "verificationUriComplete": "https://acme.effectiveai.app/device?code=BCDF-GHJK",
  "expiresAt": "2026-10-16T20:38:50.924Z",
  "expiresIn": 600,
  "interval": 5
}
```

Show the user `verificationUriComplete` and `userCode`. Keep `deviceCode` private. Then, every
`interval` seconds, exchange the device code:

```bash theme={null}
curl --request POST \
  --url "https://api.canary.effectiveai.app/api/v2/device-authorizations/exchange" \
  --header "Content-Type: application/json" \
  --data '{"deviceCode": "x1E7mH4cQk0p..."}'
```

Until the user decides, the response is `{"status": "pending", "interval": 5}`. After approval, one
response contains the key:

```json Response theme={null}
{
  "status": "approved",
  "apiKey": "sk-eai-...",
  "apiKeyId": "8b0f3c52-6d0e-4a0f-9f55-2b7c1e7d9a10",
  "tenantId": "acme",
  "expiresAt": "2027-01-14T20:28:50.924Z"
}
```

Write `apiKey` straight to the credentials file without printing the response. Later calls with
the same device code return `410`.

| Status | Code | What to do |
| - | - | - |
| `400` | `invalid_request` | Check `clientName` and `workspace`. |
| `403` | `device_authorization_denied` | The user denied the request. Stop. |
| `404` | `not_found` | The device code is wrong. Start again. |
| `410` | `device_authorization_expired` | The request expired or its key was already issued. Stop. |
| `429` | `rate_limited` | Wait the `Retry-After` seconds, then continue. |

## What the user approves

The approval page shows the code, the name the agent gave, and the address and program the
request came from. Only a signed-in user of the requested workspace can approve it. The new key has
that user's access and appears on their **API Keys** page as `<name> (agent sign-in)`. Accounts
with read-only access can't approve requests, just as they can't create API keys.

To create a key by hand instead, follow the [quickstart](/getting-started/quickstart).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.