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.

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.

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. 1Run qwryai-cli auth:login.
2. 2Copy the one-time device code from your terminal.
3. 3Open the QwryAI approval screen.
4. 4Confirm the workspace name, tenant id, and Developer & Agent Access eligibility.
5. 5Choose the permissions qwryai-cli gets.
6. 6Approve.
7. 7QwryAI 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.

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

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

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

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>

# 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"

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.

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.

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

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