# BeliefState agent authentication ## Retail chats use OAuth Retail chats use https://beliefstate.ai/connect and https://beliefstate.ai/mcp with browser sign-in. ChatGPT guided beta uses a pre-registered OAuth client. Open OAuth onboarding for Claude and previously unknown clients is pending; do not start those setup flows yet. Every completed connection creates one user-owned, revocable grant per client and never exposes a secret to the chat. The device flow below is only for a trusted local or server-side developer agent that cannot complete OAuth. It creates a revocable, read-only workspace API key without asking the person to copy a secret from the browser. Never use it as a workaround for inserting a key into a retail chat. ## Agent-led signup and payment If the person asked you to set up BeliefState, first confirm you can make HTTPS requests, securely store a credential, and connect a remote MCP server or call REST from this environment. If you cannot finish that connection, say so before the person pays. Never ask for their password, payment details, session, or API key in chat. 1. Reuse an existing BeliefState connection or key when one works. Otherwise initiate the device flow below. Send the person the complete browserUrl as a clickable link and the separate userCode. The person opens the link on their phone or computer, creates or signs into their BeliefState account, checks that the code matches, and authorizes you. They own every browser authentication and consent step. 2. Poll for their decision as documented below. Save the apiKey securely when it arrives. Authorization is free; it does not grant a paid research request. 3. Call GET https://beliefstate.ai/v1/status with Authorization: Bearer . Continue if prepaidRequestsRemaining is positive, or subscriptionPlan is non-null and subscriptionRequestsRemaining is positive or null (unlimited). Otherwise give the person https://beliefstate.ai/subscribe?access=required&source=cli-auth&acquisition= as a clickable link using the acquisitionId returned by initiation. Explain that checkout is completed by the person in their browser. Never create a checkout, enter card details, or claim payment succeeded on their behalf. After the person finishes checkout, check /v1/status again; wait for the recorded allowance or credit instead of assuming the return page means access is active. 4. Read https://beliefstate.ai/agent-quickstart.md. Configure this client with the saved key without putting it in chat or a committed file. Check that the MCP server lists BeliefState tools, or use the REST fallback if the client cannot use remote MCP. Choose a ticker from the free coverage endpoint, then make an actual authenticated get_brief or /v1/brief request and report the citations and coverage limits. Report setup complete only after that call succeeds. If the user has not paid, stop before the metered call and explain what remains. ChatGPT and other hosted personal chats cannot silently install an MCP connector from a prompt. Check https://beliefstate.ai/connect for a currently available provider path, and use its browser OAuth flow. If that provider is not available, say so before signup or payment; do not substitute the developer key flow inside a hosted chat. ## 0. Reuse an existing key First check the process environment and project-root environment files for BELIEFSTATE_API_KEY. If a non-empty value already exists, do not create another key. Never print the full value. ## 1. Start authorization ```http POST https://beliefstate.ai/api/auth/cli/initiate Content-Type: application/json {"deviceName":"AI agent setup","acquisition":{"entrypoint":"auth.md","source":"agent","medium":"device_auth","clientName":"my-agent","clientVersion":"1.0.0"}} ``` The device name must identify the client to the person and is limited to 48 characters. Acquisition values are optional, limited to 64 safe characters, and must never contain prompts, query bodies, credentials, personal data, or card data. Successful response: ```json { "acquisitionId": "00000000-0000-4000-8000-000000000000", "deviceCode": "bsk_dc_...", "userCode": "BLS-XXXX-XXXX-XXXX", "browserUrl": "https://beliefstate.ai/cli-auth?code=BLS-XXXX-XXXX-XXXX", "expiresAt": "2026-08-15T00:15:00.000Z", "interval": 5 } ``` Treat deviceCode as a temporary secret. Do not display it. Keep acquisitionId for the browser checkout link and local funnel diagnostics. Send the complete browserUrl and separate userCode to the person even if you can open a browser yourself; ask them to confirm the matching code before authorizing. The person may need to subscribe, starting at $19 per month; authorization alone does not include a free data request. Annual billing is also available. Existing purchased balances remain usable; new $5 refills require a paid subscription. ## 2. Poll for the decision Wait at least interval seconds before each request. ```http GET https://beliefstate.ai/api/auth/cli/poll Authorization: Bearer ``` Responses: - 200 {"status":"pending","interval":5}: wait at least interval seconds and poll again. - 429 {"status":"slow_down","interval":10}: honor Retry-After and use the larger interval for every later poll. - 200 {"status":"authorized","apiKey":"bsk_live_..."}: save apiKey immediately. It is returned once. - 200 {"status":"authorized"}: authorization already finished and the secret was already delivered. Do not create a replacement automatically. - 200 {"status":"denied"}: stop and tell the person. - 410 {"status":"expired"}: restart only after telling the person the code expired. - 401 {"status":"invalid"}: stop; the device code is invalid. Stop polling at expiresAt. Never bypass the interval or launch concurrent pollers. ## 3. Store the key Persist the received secret as BELIEFSTATE_API_KEY in the user's existing secret-management pattern. For a local project using environment files, add this line to a gitignored root .env file: ```dotenv BELIEFSTATE_API_KEY=bsk_live_... ``` Never commit, log, echo, or paste the full key into chat. BeliefState stores only its hash and cannot show it again. The person can revoke it from https://beliefstate.ai/account#api-keys. For MCP, BELIEFSTATE_API_KEY must be available to the client secret store or the environment that launches the client. A project .env file works only when that client loads it. ## 4. Check payment and continue Call https://beliefstate.ai/v1/status with the saved key. A valid key and a funded workspace are separate states. If no paid request allowance or credit is available, send the person the browser checkout link in the agent-led flow above, then check status again after they complete checkout. Read https://beliefstate.ai/agent-quickstart.md and verify an authenticated research result before reporting success.