Skip to content
$349 once

Troubleshooting.

Fix sign-in failures, 401 and 403 answers, missing tools, expired approvals, clock questions and a connection that never appears.

Oct 23, 2026
On this page

This page is for the platform owner and for business owners whose AI client won't connect or can't do something. Start with the symptom.

Check the basics first

  1. Open your account menu, then choose AI connections. For a business owner, the menu item appears only when the current plan includes Agent API, individual access is allowed and AI connections are on. The platform owner can still open it from their account menu to turn the feature on. See Overview.
  2. Read the line under your address. Browser sign-in is ready. means the setup checks out.
  3. Check the connection card. It shows Ended or Expired when the connection is over.
  4. Open View activity on the card to see whether the AI client reached Reward Loyalty at all.

Browser sign-in won't start

The line under your address on the AI connections page names the cause. Each message has one fix.

The page says What to do
Browser sign-in is off. Keys still work. Turn on Browser sign-in in the Settings section of the page, or connect with a key.
Browser sign-in needs HTTPS. Set APP_URL in .env to the public https:// address, clear the config cache if your host caches it, and reload the page. A key changes how the client authenticates; it does not replace HTTPS.
Browser sign-in needs the app at the root of its domain, and this one runs in a folder. Sign-in discovery lives at the root of the host, at /.well-known, so an app served from a folder such as https://example.com/loyalty can't publish it. Move the app to the root of a domain or subdomain. Or connect with a key, as Connect Claude Code, Cursor and VS Code explains.
The web server or a firewall blocks /.well-known, so browser sign-in can't start. Allow the /.well-known path through to the app, then check it as shown below. Or connect with a key.

A blocked /.well-known

An AI client starts sign-in by fetching a document under /.well-known. Some hosts and firewalls serve that path themselves or block it. Check it from your own computer:

curl -i https://your-domain.com/.well-known/oauth-protected-resource/mcp

A working install answers 200 with a JSON document whose resource is your /mcp address. A 403, a 404 page from the host, or an HTML page means the path never reaches the app. Ask your host or firewall administrator to pass /.well-known to the app, then check again. A 404 that comes from Reward Loyalty itself means AI connections or browser sign-in are off, or the app runs in a subfolder.

The sign-in page says something is wrong

  • This connection request isn't valid. The client sent a request Reward Loyalty doesn't recognize, such as an unknown client or a redirect address that doesn't match. Start the connection again from the AI client. The page shows a code for support.
  • This sign-in request expired. A request lasts 30 minutes and works once. Start again from the AI client.
  • Claude can't connect to this account, with your client's name in place of Claude. The account you are signed in with can't connect an AI client. Only the platform owner and business owners can. A business owner also needs the Agent API switch and a plan with the Agent API. The page says which reason applies.
  • Claude wants to connect, with the buttons Sign in as the platform owner and Sign in as a business owner. You aren't signed in. Choose the account the client should act for. You come back to the same request afterwards.
  • Which account should Claude act for? You are signed in as the platform owner and as a business owner in the same browser. Choose one.

401 answers

A 401 means Reward Loyalty doesn't accept the credential.

Code Cause Fix
AUTH_MISSING_KEY The request carried no credential. Send Authorization: Bearer YOUR_KEY.
AUTH_INVALID_KEY The key is wrong or malformed, or a browser sign-in connection ended, expired or its token ran out. Copy the key again, or connect the client again. A sign-in token works at /mcp only.
AUTH_KEY_REVOKED The key was ended. Create a new key.
AUTH_KEY_EXPIRED The key passed its end date. Create a new key and choose a longer end date.

After 20 failed attempts in a minute from one address with one key prefix, Reward Loyalty answers 429 before it checks the key. Wait a minute.

403 answers

A 403 means Reward Loyalty knows the caller and refuses the request.

Code Cause Fix
ORIGIN_NOT_ALLOWED The request came from a web page, so it carried an Origin header. Call from a server or a desktop client. A key never belongs in a browser page.
AUTH_WRONG_ROLE The key's role doesn't fit the path, or the owner can't connect an AI client. Use a key of the right role. Admin managers and business sub-roles can't connect.
FEATURE_DISABLED A switch, a plan feature or a permission is off. Ask the platform owner to turn on the Agent API, add it to the plan or grant the permission.
AUTH_INSUFFICIENT_SCOPE The connection's access doesn't cover this call. Create a connection with more access. details.required_scope names the scope.
AUTH_OWNER_INACTIVE The owner's account is inactive. Reactivate the account. Every key it owns works again.
DEMO_MODE A demo installation refuses changes. Use your own installation.

Limits, errors and retries lists every code.

A tool or job is missing

An AI client lists only the tools its connection may use. A missing tool has one of these causes.

  1. The access is too low. Read everything offers no tools that change anything. Create a connection with Read and make changes you approve, or a Custom connection that allows changes in that area. The Read and make changes you approve choice permits reads and immediate changes as well as actions requiring approval. Selecting this does not make every change wait for you.
  2. The plan doesn't include the feature. A business owner doesn't get tools for a feature the plan lacks, such as email campaigns or webhooks. get_plan_and_usage shows what the plan includes. The platform owner can change it.
  3. The permission is off. The platform owner can withdraw a business's Integration API keys permission or a feature permission on its Permissions tab.
  4. The tool is inside a family. When a connection would otherwise get too many tools, the platform keeps some families out of the list. They stay available through describe_tool_family and run_family_tool, or admin_describe_tool_family and admin_run_family_tool for the platform owner. Ask the AI client to use them. See Admin tools.
  5. The money records are off. Stored-money reads need Include money records.
  6. The client kept an old list. After a plan or permission change, reconnect or refresh the tool list in the client.
  7. The task has no tool on purpose. See Access and security.

A change didn't happen

  • The AI client says it prepared the change. Open Approvals and decide. Nothing runs before that. See Approvals.
  • The request expired. A request closes 10 minutes after the AI client prepared it. Ask for the change again.
  • Not run: the record changed. This can mean the record changed or execution failed partway. Check the affected records and activity before preparing another request; some of the work may already have happened.
  • A refusal with a code. Read the code in Limits, errors and retries. VALIDATION_FAILED and WRITE_REFUSED say what to fix.

The connection never appears

The waiting line on the AI connections page stays on Waiting for Claude… (or the client you picked) until a client connects.

  1. Check that the client's connector status says connected. If sign-in opened and you chose Allow access, the card appears within seconds.
  2. Look at the line under your address. If it isn't Browser sign-in is ready., fix it first.
  3. Open the activity log and look for Agent sign-in refused entries. A refused attempt names its reason. It never includes key material.

A clock is wrong

Reward Loyalty sets and checks every sign-in time, key end date and approval window on its own server clock. The AI client gets each lifetime in seconds. A wrong clock on your computer or in the AI client doesn't end a connection early or keep it alive longer. If times in the activity log look wrong, keep the server's clock in sync with a time server.

Slow or rate-limited

A 429 with RATE_LIMITED means a limit was reached. details.scope says which. Wait for Retry-After seconds. A connection made on the AI connections page allows 120 requests a minute. Behind a reverse proxy, the operator must set TRUSTED_PROXIES, or every caller shares one network address. See Limits, errors and retries.