Skip to main content
Paste this into your agent, such as Claude Code:
Prompt
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):
On Windows PowerShell:
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:
After approval it prints only the signed-in identity and where it saved the key:
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:
On Windows, the file is %APPDATA%\effective\credentials:
Then confirm the identity with GET /users/me and 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:
Response
Show the user verificationUriComplete and userCode. Keep deviceCode private. Then, every interval seconds, exchange the device code:
Until the user decides, the response is {"status": "pending", "interval": 5}. After approval, one response contains the key:
Response
Write apiKey straight to the credentials file without printing the response. Later calls with the same device code return 410.

​
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.