Skip to main content

AI Agent Integration

Want an AI agent — like an AI assistant or automation tool (e.g. Viktor AI) — to operate your Dashboard on your behalf?

Because AI agents look like automated traffic to Propcart's normal login security, they can't sign into the Dashboard the same way a human does. The AI Agent Integration gives an agent its own dedicated Dashboard account, scoped to whatever role and permissions you choose, and revocable at any time.

This guide explains how to set it up. It should take about five minutes.

info

Only the account owner (the person who originally created your Propcart account) can add, edit, or remove AI agents. This can't be delegated to other staff, even ones with full "All Access" permissions.

Step 1: Create a dedicated staff user for the agent​

Never assign an AI agent to a human staff member's existing account. Create a brand new staff user just for the agent.

The agent's user must belong only to your Propcart account. An AI agent can't sign in as the account owner, as a user that also has access to another Propcart account (even one that's yours), or as a Propcart support account. If you run more than one Propcart account, create a separate agent user in each.

  1. Go to your Roles & Permissions Settings and create an "AI Agent" Role scoped to only what the agent needs to do. See Roles & Permissions for how to create a limited-access role.
  2. Go to your Users list and click the New User button.
  3. Give it a clear, descriptive display name, like "Viktor AI Agent". This is the name you'll see in the Activity for agent-related events.
  4. Enable Staff? and assign it the "AI Agent" Role created in Step 1.
  5. Save the user.
info

Only staff show up when you go to connect an AI agent in Step 2. If you skip enabling Staff? in Step 1, you won't be able to select this user.

Staff an AI agent can't sign in as are listed but can't be selected, with the reason next to their name (for example, "also has access to other Propcart accounts").

Step 2: Add the AI agent in Settings​

  1. Go to Settings > Integrations.
  2. Scroll to the AI Agent Integration section and click Add AI Agent.
  3. Select the dedicated user you created in Step 1 from the dropdown.
  4. Click Add.

Step 3: Copy the secret​

After you click Add, Propcart generates a secret and shows it to you once.

caution

Copy this secret now. Propcart doesn't store it and can't show it to you again. If you lose it, delete the AI agent (see below) and add it again to get a new one.

Send this secret securely to whoever operates the AI agent (for example, your AI agent's support team) — it's the credential their system uses to sign in as the dedicated user you created in Step 1. Treat it like a password: avoid pasting it into email or chat in plain text if you can help it.

Managing an AI agent​

Every AI agent you've added shows up as a row under Settings > Integrations > AI Agent Integration, labeled with its assigned user's name. Click a row to open it.

  • Active toggle — turn an agent off temporarily without deleting it. Turning it off immediately signs the agent out of any active session. Turning it back on lets it sign in again using the same secret you already gave its operator — no new secret needed.
  • Delete — permanently removes the agent and immediately signs it out of any active session. There's no undo, and the deleted secret can never be reused. If you need this agent again later, add it again to get a brand new secret.

If a row shows Can't sign in, the agent's user has changed since you added it, so the agent will be refused. Open the row to see why, then see If the agent can't sign in.

If the agent can't sign in​

When sign-in is refused, the Dashboard tells the agent why, and the agent's row in Settings shows Can't sign in. Here's how to fix each reason:

  • Its user also has access to other Propcart accounts — delete the agent, create a new staff user that belongs only to this account (see Step 1), and add the agent again with that user.
  • Its user is the account owner — delete the agent and add it again with a dedicated staff user.
  • Its user is a Propcart support account — delete the agent and add it again with a dedicated staff user.
  • Its user no longer exists — delete the agent and add it again with a dedicated staff user.
  • Its user isn't staff here — open the agent's user from your Users list, turn on Staff?, choose a role and save.

For your AI agent's developers: how it authenticates​

Everything above is for prop house staff. This section is for whoever builds or operates your AI agent — share it with them once you have a secret from Step 3.

Important: your AI agent's own code does not need to call any API or manage tokens itself. The Dashboard already has this logic built in. Your agent just needs to set two values in the browser before the Dashboard page loads, then use the Dashboard normally from there.

1. Inject values before navigating to the Dashboard​

Using your browser automation framework's pre-navigation hook (for example, Playwright's page.addInitScript() or Puppeteer's page.evaluateOnNewDocument()), set:

window.__PROPCART_AGENT__ = true;
window.__PROPCART_AGENT_SECRET__ = '<the secret from Step 3>';
caution

This must run before the Dashboard's own JavaScript executes. Injecting these values after the page has already loaded is too late — the Dashboard only reads them once, at startup.

If your account is not on Propcart's North America server (the default), also set which region to use, or the agent will try to sign in against the wrong one and fail:

window.localStorage.setItem('projectId', 'propcart-eu'); // or propcart-au / propcart-br

Ask your Propcart contact which server your account is on if you're not sure. North American accounts can skip this.

If your automation framework can't run scripts before page load, this integration won't work. Let us know if this is the case.

2. Navigate to the Dashboard and sign in​

Navigate to https://dash.propcart.com as normal. The Dashboard detects the values from step 1 and signs itself in as the dedicated staff user you created in Step 1 — usually within a couple seconds of page load. From there, your agent can interact with the Dashboard UI like any other admin user, scoped to whatever permissions its Role allows.

If sign-in fails, the page lists each sign-in step and shows the reason under the step that failed. Pass that reason on to the account owner, who can fix it as described in If the agent can't sign in.

Previewing webstore drafts​

An AI agent can also sign into your Propcart Pro Webstore to preview draft pages before you publish them, just like your staff using View Draft Pages. It uses the same secret and the same two values from step 1 above.

  1. Set window.__PROPCART_AGENT__ and window.__PROPCART_AGENT_SECRET__ before the page loads, exactly as for the Dashboard. Webstores already know which server they're on, so you don't need to set projectId.
  2. Navigate straight to the draft, e.g. https://<your webstore>/drafts/<pageId>, or a saved revision at https://<your webstore>/drafts/<pageId>/revisions/<revisionId>. The webstore signs the agent in and stays on that page. You can find the link with View Draft Page in the Dashboard.
  3. Wait until the page's <html> element has data-agent-sign-in="success" before checking or capturing the page. If sign-in fails, it becomes data-agent-sign-in="error" and the page shows the reason.

The webstore session is only for previewing. The agent can view draft pages and anything a visitor can see, but it can't use account pages, set lists, quote requests, orders, favorites, carts, or contact forms, and it never creates a customer record. Turning the agent off or deleting it signs it out of your webstore too.

tip

If sign-in fails because the agent's user "isn't set up on your webstore yet," the account owner can fix it in the Dashboard: open the agent's user from your Users list, change its role to any other role and save, then change it back and save.

Notes​

  • Each staff user can be assigned to only one AI agent at a time.
  • An AI agent's user must belong only to your Propcart account.
  • Only the account owner can add, edit, or delete AI agents — not other staff, regardless of their role or permissions.