Developer & Agent Access

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.

The QwryAI app keeps Settings > Security focused on credential management. Use it to generate or revoke API keys and disconnect OAuth clients; use this guide for endpoint URLs, client setup, examples, and troubleshooting.

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

npm install -g qwryai-cli
qwryai-cli --help

OAuth device login is recommended for interactive CLI use.

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. Approve developer access.
6. QwryAI saves credentials to ~/.qwryai/credentials.json.

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

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

1. Open your QwryAI workspace.
2. Go to Settings > Security.
3. Find API keys.
4. Confirm Paid plan enabled.
5. Select Generate New Key.
6. Choose an expiration.
7. Copy the key immediately because the full value is shown once.

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.

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

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

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

# 2. Confirm the current workspace
qwryai-cli auth:status --verify

# 3. List chatbots
qwryai-cli chatbots:list

# 4. Create a conversation
qwryai-cli conversations:create --chatbot <chatbot-id>

# 5. Send a message
qwryai-cli conversations:send <conversation-id> --content "I need help with my order"

# 6. Search knowledge
qwryai-cli knowledge:search --chatbot <chatbot-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.

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.

{
  "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 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, tenant id, and Developer & Agent Access eligibility before approving developer access.

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

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

curl -fsS "$QWRYAI_API_URL/me" \
  -H "Authorization: Bearer $QWRYAI_API_KEY"

curl -fsS "$QWRYAI_API_URL/me" \
  -H "X-API-Key: $QWRYAI_API_KEY"

Developer access does not expose billing, user-management, destructive delete, or admin configuration tools.

1. Open Settings > Security.
2. In API keys, find the key.
3. Select revoke. Revoked keys stop working immediately.
4. In OAuth connections, find the Claude or qwryai-cli connection.
5. Select disconnect. Disconnecting an OAuth client revokes its access and refresh tokens immediately.

qwryai-cli auth:logout

• 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.
• OAuth client still has access: disconnect it under OAuth connections, then ask the user to reconnect if access is still needed.
• CLI command failed in CI: check error.code, error.statusCode, or error.httpStatus in the JSON output.
• A tool is missing: confirm the credential has the matching scope and the workspace is on a paid active plan.