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

# Agent connection instructions

> Instructions for agents to reuse an Effective connection or request browser approval, verify access, and continue the user’s task.

These instructions are for the agent. For the human connection steps, see
[Use with AI](https://docs.effectiveai.app/getting-started/using-with-agents.md).

## Check for an existing connection

Reuse an API key already configured in your environment before requesting new access.
Check `EFFECTIVE_API_KEY`, or load the credentials file described below without printing its contents. Verify the connection with `GET /users/me`.

Report the returned user and workspace. If the user requested a particular workspace, confirm it
matches before continuing. If the connection is valid for that workspace, skip sign-in and
[continue the user's task](#continue-the-users-task).

A `401` means the credential is invalid or expired; use the approval flow below to obtain a new one.
For a `403`, report the permission failure rather than treating a new key as a way around it.
For a network or service failure, report the error without creating another key.

## Connect through device approval

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.
* Send API keys only to `https://api.effectiveai.app`. Never forward them to a download
  storage host or include them in a URL.
* Show the user the link and code, then wait for them to approve in the browser.
* If the user denies the request or it expires, say so and stop. Start again only if the user asks.

### 1. Find the workspace

Use the connected account’s workspace, or ask the user if it is unknown. 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 sign-in and waits up to 10 minutes for browser approval. Run it in the
background and read its output. Show the user the printed link and code immediately and
wait for them to approve. The script then receives and saves the key.

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

```bash theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
curl --fail --output effective-setup.sh https://api.effectiveai.app/api/v2/device-authorizations/setup.sh
EFFECTIVE_CLIENT_NAME="Claude Code" bash effective-setup.sh acme
```

On Windows PowerShell:

```powershell theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
Invoke-WebRequest -UseBasicParsing https://api.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. The script prints:

```text theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
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 request expires in 10 minutes.
```

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

```text theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
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={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
export EFFECTIVE_API_KEY="$(cat ~/.config/effective/credentials)"
```

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

```powershell theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
$env:EFFECTIVE_API_KEY = Get-Content -Raw "$env:APPDATA\effective\credentials"
```

Confirm the identity:

```bash theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
curl --request GET \
  --url "https://api.effectiveai.app/api/v2/users/me" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY"
```

Report the returned user and workspace, then continue the user's task. If the identity does not
match the requested workspace, stop and resolve that mismatch with the user before making further
requests. The key lasts 90 days and can be revoked from **API Keys**.

## Continue the user's task

If the user already gave you a task, continue it after verifying the connection. Otherwise, ask what
they want to research or do. Do not run an unrelated product search just to complete setup.

* [The documentation index](https://docs.effectiveai.app/llms.txt) lists the available pages.
* [Research guides](https://docs.effectiveai.app/guides/index.md) map research questions to workflows. Read the relevant guide
  and operation reference when needed.
* Append `.md` to a page URL for Markdown, for example `/getting-started/quickstart.md`.
* [The API catalog](https://docs.effectiveai.app/.well-known/api-catalog) links to the OpenAPI spec. The page menu also offers
  **Download API spec**.
* For shared file URLs, text, downloads, and citations, use
  [Read and cite documents](https://docs.effectiveai.app/guides/read-filing-documents.md).

When searching filing text, pass the user's research goal as `intent`. Search requires it, but it
does not change the results or their order.

## Without the scripts

If neither script can run in your environment, make the same two calls yourself. Neither needs an
API key. Capture responses inside your program, not in tool output or logs: the first contains a
private device code and the exchange returns the API key once. The examples below show request and
response shapes; do not run them in a way that prints their responses.

Start the sign-in:

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

```json Response theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
{
  "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` and wait for them to approve in the browser. Keep `deviceCode` private. Then, every
`interval` seconds, exchange the device code:

```bash theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
curl --request POST \
  --url "https://api.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={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
{
  "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. Check it before retrying. |
| `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 [API quickstart](https://docs.effectiveai.app/getting-started/quickstart.md).


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