# Developer & Agent Access

Connect QwryAI to external AI tools, MCP clients, scripts, and CLI workflows.

## Availability

> **Documentation Index**: Fetch the complete documentation index at /llms.txt. Use this file to discover all available QwryAI docs before exploring further.

Developer and agent access is available only when your workspace has an active paid subscription. Access follows the current workspace subscription, so downgraded, canceled, inactive, or suspended workspaces stop API-key, OAuth, MCP, and CLI usage at validation time.

Every API key and OAuth connection acts on behalf of the member who created it. When you create a key or approve a connection, you choose which permissions it gets, from the ones your role holds.

A credential never does more than its creator's current role allows. If your role changes, every key and connection you created narrows with it right away; if you leave the workspace, they stop working.

> **Reviewed changes**: Tools that change settings, sources, actions or procedures never apply on their own. They return the exact before and after changes for review, and nothing changes until the change is approved with apply_change.

## Installation

Install the QwryAI CLI and verify it is available from your shell.

```bash
npm install -g qwryai-cli
qwryai-cli --help
```

## Authentication

OAuth device login is recommended for interactive CLI use.

```bash
qwryai-cli auth:login
qwryai-cli auth:status
qwryai-cli auth:status --verify
qwryai-cli auth:logout
```

1. Run qwryai-cli auth:login.
2. Copy the one-time device code from your terminal.
3. Open the QwryAI approval screen.
4. Confirm the workspace name, tenant id, and Developer & Agent Access eligibility.
5. Choose the permissions qwryai-cli gets.
6. Approve.
7. QwryAI saves credentials to ~/.qwryai/credentials.json.

Use API keys for OpenClaw, Cursor, custom MCP clients, scripts, CI jobs, and headless automation.

> **Credential handling**: Store existing credentials securely in your local environment or secret manager.

Keep QWRYAI_API_KEY as a placeholder in reusable setup snippets. Paste the one-time key only into your local environment or secret manager.

> **Key rotation**: Rotate API keys when a teammate leaves, a script is retired, or a key may have appeared in logs, screenshots, or support messages.

Create API keys in Settings > API keys. Choose the permissions the key needs; a key cannot get permissions your role does not hold.

```bash
export QWRYAI_API_KEY=<your-qwryai-api-key>
```

When both OAuth credentials and QWRYAI_API_KEY are present, qwryai-cli uses OAuth credentials first and falls back to the API key when no OAuth session is stored.

## Custom API URL

For staging, self-hosted, or tunneled environments, point the CLI and scripts to a different QwryAI API origin.

```bash
export QWRYAI_API_URL=https://api.qwryai.com/public/v1
export QWRYAI_AUTH_SERVER=https://api.qwryai.com
export QWRYAI_MCP_URL=https://api.qwryai.com/mcp
```

## Endpoints

| Surface | URL |
| --- | --- |
| Public API | https://api.qwryai.com/public/v1 |
| MCP | https://api.qwryai.com/mcp |
| Claude MCP | https://api.qwryai.com/mcp-oauth |
| OAuth authorization | https://www.qwryai.com/oauth/authorize |
| Device approval | https://www.qwryai.com/oauth/device/verify |

## Quick Start

```bash
# 1. Authenticate with OAuth
qwryai-cli auth:login

# 2. Confirm the workspace and the permissions this credential holds
qwryai-cli auth:status --verify

# 3. See the tools you can use
qwryai-cli tools:list

# 4. List agents
qwryai-cli tools:call list_agents

# 5. Start a conversation and send a message
qwryai-cli tools:call create_conversation --args '{"chatbotId":"<agent-id>"}'
qwryai-cli tools:call send_message --args '{"chatbotId":"<agent-id>","conversationId":"<conversation-id>","content":"I need help with my order"}'

# 6. Search knowledge
qwryai-cli tools:call search_knowledge --args '{"chatbotId":"<agent-id>","query":"refund policy"}'
```

All CLI output is JSON. Authentication and API failures exit with a nonzero code and may include machine-readable error.code, error.statusCode, or error.httpStatus fields for scripts and CI jobs.

## Commands Overview

| Command | Description |
| --- | --- |
| qwryai-cli auth:login | Authenticate with OAuth device login. |
| qwryai-cli auth:status | Show the stored authentication method. |
| qwryai-cli auth:status --verify | Verify stored credentials against QwryAI. |
| qwryai-cli auth:logout | Revoke the stored OAuth grant and remove local credentials. |
| qwryai-cli mcp:config | Print a secret-safe MCP config using Bearer ${QWRYAI_API_KEY}. |
| qwryai-cli tools:list | List the tools this credential may use, with their input schemas. |
| qwryai-cli tools:call <name> --args '{...}' | Call one tool with a JSON object of arguments. |
| qwryai-cli apply <reviewId> | Apply a change a tool prepared, after you checked its before and after. |

## MCP Clients

QwryAI MCP is a hosted remote HTTPS endpoint, not a local stdio MCP server. Configure clients to call the hosted MCP URL with a bearer token.

For OpenClaw-style clients, define both a remote server and a named qwryai server if the client supports both shapes.

```json
{
  "remote": {
    "url": "https://api.qwryai.com/mcp",
    "headers": {
      "Authorization": "Bearer ${QWRYAI_API_KEY}"
    }
  },
  "mcpServers": {
    "qwryai": {
      "url": "https://api.qwryai.com/mcp",
      "headers": {
        "Authorization": "Bearer ${QWRYAI_API_KEY}"
      }
    }
  }
}
```

For Cursor-style MCP configuration, add a qwryai server with the same URL and bearer header. Compatible custom MCP clients can use the same hosted remote HTTPS server definition.

## Claude OAuth

Claude should use https://api.qwryai.com/mcp-oauth through OAuth. Do not paste a QwryAI API key into Claude. Confirm the approval screen shows the correct workspace name and tenant id, choose the permissions Claude gets, then approve.

When Claude prepares a change, it shows you the before and after. Claude applies it only after you approve it in the conversation.

## Public REST

Scripts can use the public REST facade with an API key.

```bash
export QWRYAI_API_URL=https://api.qwryai.com/public/v1
export QWRYAI_API_KEY=<your-qwryai-api-key>

# Workspace, permissions and tools for this key
curl -fsS "$QWRYAI_API_URL/me" \
  -H "Authorization: Bearer $QWRYAI_API_KEY"

# Tool list with input schemas
curl -fsS "$QWRYAI_API_URL/tools" \
  -H "Authorization: Bearer $QWRYAI_API_KEY"

# Call a tool
curl -fsS -X POST "$QWRYAI_API_URL/tools/list_agents" \
  -H "Authorization: Bearer $QWRYAI_API_KEY" \
  -H "Content-Type: application/json" -d '{}'

# Apply a reviewed change
curl -fsS -X POST "$QWRYAI_API_URL/reviews/<reviewId>/apply" \
  -H "Authorization: Bearer $QWRYAI_API_KEY"
```

## Permissions and tools

MCP, the public REST API, qwryai-cli and Backstage share one set of tools. Each tool needs one permission, and a credential sees only the tools its permissions allow. Run get_account_context, GET /me or qwryai-cli auth:status --verify to see what a credential holds now.

| Permission | What it allows |
| --- | --- |
| Chat with agents | List agents, start customer conversations, send customer messages, and search knowledge and product documentation. |
| Manage conversations and helpdesk | Read conversations, tickets and analytics; reply as a human agent, add notes, resolve, and pause the AI. |
| Read agent settings | Instructions, model, chat interface, sources, knowledge gaps, integrations, webhooks and deploy status. |
| Change agent settings | Instructions, model, chat interface, styles, spam and country rules, and deploy channels. |
| Change sources and training | Add, edit, delete and restore sources, answer knowledge gaps, and start training. |
| Read actions and procedures | Actions, procedures, drafts, publication state, widgets and templates. |
| Change actions and procedures | Create, edit, enable, disable and delete actions, procedures and webhooks. |
| View plan and credits | Plan, credit balance and credit usage. |

Tools that work on one agent take its id from list_agents as chatbotId. Tools that change settings return status review_required with a reviewId and each change's before and after; apply_change applies that exact review once. A review expires after 15 minutes, and it is refused if the resource changed since.

Developer access never exposes user management, custom field administration, or workspace administration.

## Revoke Access

Delete API keys in Settings > API keys. To revoke the OAuth grant for your local CLI session and remove local credentials, run:

```bash
qwryai-cli auth:logout
```

## Troubleshooting

- Key is rejected: confirm the full key was copied, has not expired, and has not been revoked.
- Access stopped after plan change: Developer access follows the current active workspace subscription plan.
- Claude asks for approval: complete the QwryAI OAuth approval screen.
- OpenClaw or Cursor cannot connect: confirm the client is using remote HTTPS MCP and a bearer API-key header.
- CLI is not authenticated: run qwryai-cli auth:login again or set QWRYAI_API_KEY.
- CLI access is no longer needed: run qwryai-cli auth:logout to revoke the stored OAuth grant and remove local credentials.
- CLI command failed in CI: check error.code, error.statusCode, or error.httpStatus in the JSON output.
- A tool is missing: check the permissions in auth:status --verify. The credential needs the permission, and so does its creator's current role.
- Access stopped for one teammate's keys: the member who created them left the workspace or was suspended. Create new credentials as an active member.
- apply_change was refused: the review expired, was already applied, or the resource changed. Call the tool again for a fresh review.