Connect ChatGPT — BoxOwl Docs

What you'll end up with

A private Custom GPT in your ChatGPT account titled something like "BoxOwl Vault" with one Action defined against https://api.boxowl.me/api/v1/. The Custom GPT authenticates every request with your agent token as a static Bearer (ChatGPT's Action-auth flow). No data leaves your BoxOwl account except whatever ChatGPT asks for in a given conversation — and only what your token's scopes allow.

Custom GPTs need ChatGPT Plus or higher. The agent token model works the same on Free vs Premium BoxOwl tiers — Free users just get one token at a time.

Step 1 — Create an agent token

BoxOwl Android app: Settings → AI Agent Connections → New. Suggested name "ChatGPT Custom GPT". Starter scopes: vault:read, profile:read, agent:query. Copy the plaintext token.

See Agent tokens for the full scope vocabulary if you want write capabilities. Be deliberate about write scopes for ChatGPT — its Action surface doesn't expose BoxOwl's confirmation-envelope flow, so writes go through whenever the model decides to call the API.

Step 2 — Start a new Custom GPT

In ChatGPT: My GPTs → Create a GPT. Skip the conversational wizard ("Configure" tab). Set:

Name: BoxOwl Vault
Description: My personal data vault.
Instructions: You can read and write the user's BoxOwl vault via the configured Action. Always cite which scope a call used. Refuse anything outside the granted scopes.

Step 3 — Add the Action

Under Actions → Create new action, paste an OpenAPI 3.0 schema for the BoxOwl endpoints you want exposed. A minimal read-only example:

openapi: 3.1.0
info:
  title: BoxOwl Vault
  version: "1.0"
servers:
  - url: https://api.boxowl.me/api/v1
paths:
  /vault/{category}:
    get:
      operationId: getVaultCategory
      summary: Read one vault category
      parameters:
        - name: category
          in: path
          required: true
          schema:
            type: string
            enum: [identity, contact, address, payment_method, login, secure_note]
      responses:
        "200":
          description: OK

The full schema (writes, batch, etc.) lives at API → Vault — pull only the endpoints you actually want ChatGPT to use.

Step 4 — Wire the auth

Still in the Action editor:

Authentication type: API Key
Auth Type: Bearer
API Key: paste your bxusr_… token from Step 1

Save the GPT. ChatGPT stores the token encrypted-at-rest in your account; it isn't shared with other ChatGPT users.

Step 5 — Test a query

Open a chat with your new Custom GPT and ask:

What's my primary shipping address?

ChatGPT will route the call through the configured Action, BoxOwl returns the JSON, and ChatGPT renders it inline. The first invocation prompts you ("BoxOwl Vault wants to use the configured Action") — accept and the rest of the conversation runs frictionlessly.

Manage the connection

Revoke the agent token any time from BoxOwl Settings → AI Agent Connections — the next ChatGPT call gets a 401 and the Custom GPT stops being able to read your data. To rotate without breaking the Custom GPT, create a new token in BoxOwl, paste it into the Action's API Key field, then revoke the old one.

Connect ChatGPT to your BoxOwl vault