Connection settings and access reference

For: owners who manage connections and developers who configure MCP or HTTP clients.

A connection can use only its selected access within the person's current permissions. Sensitive actions need approval of the specific request, from your decision or a matching rule with limits.

To connect your own app, start with Connect your AI. This reference covers delegation, credentials and exact access rules.

Connect through browser sign-in

AI is optional. Pepper works without an AI account. You choose each connection's access, and you confirm invoice and quote issuance.

The owner can also connect a client from the console and choose another person for it to act as.

1. Open Settings > Agent connections as the owner.
2. Click Enable client connections if access is off.
3. Click Copy address and add that address as a remote MCP server in your client.
4. Start the connection from your client.
5. Sign in to Pepper as the owner.
6. Check the client name and the browser's return address.
7. Clear any Permitted access the client does not need.
8. Choose an active staff member in Delegate as user and set the expiry.
9. Click Allow access.

Enabling connections allows browser sign-in. It grants no client access on its own. A connection lasts between 1 and 30 days.

Click Deny if the client or return address is wrong. Allow a return to your own computer only for a connection you started.

The browser returns to the client. The client manages access tokens and refreshes them within the connection's expiry.

Browser sign-in needs HTTPS at the root of your domain or subdomain. It does not support an installation in a subfolder.

An unregistered client or return address shows This connection request cannot be used. Start a new connection from the client.

See Use Pepper from your AI client for tested clients and example requests.

Connect AI in a customer workspace

A workspace connection can use only that business’s records, within the person’s workspace role, shop access and plan. It cannot reach the provider’s records or another workspace.

Supported work includes the business’s website, shop, stock, widgets, bookings, listings, analytics, people, team and catalogue. Shop actions use that business’s orders, invoices, credit notes, refunds and Stripe account. The AI cannot read or enter Stripe keys.

Both installation access and the workspace’s AI for this account switch must be on. Each person connects their own app. A person who also works on the provider’s team needs a separate connection for that team. Check Where it works on the consent page.

The connection’s person reviews requests in that workspace’s Agent approvals. The workspace owner can stop any connection there. Turning off either switch or removing the person from the workspace stops access. See the workspace tool list.

Create a pasted-credential connection

Use this method for a client that supports bearer authentication. The credential works with both MCP and HTTP.

1. Open Advanced connection options on the Agent connections page.
2. Enable agent access and save if it is off.
3. Enter a Connection name and Purpose.
4. Choose an active staff member in Delegate as user.
5. Set Expires after (days, 1–30).
6. Select the Permitted access the client needs.
7. Click Create connection.
8. Copy the credential into your client's secret store, then click Close.

The credential appears once. Keep it out of URLs, browser storage, source code and logs. If you lose it, revoke the connection and create another.

For MCP, use the address at the top of the page and the client's bearer-credential setting. For HTTP, use the API address under Advanced connection options and send Authorization: Bearer <credential>.

Use a server or command-line client for direct HTTP calls. Browser JavaScript requests with an Origin header fail.

See what a client can do

Jobs gives example requests and the access each job needs. Apps and access shows the tools for each installed app. Expand an app to read its tool list. Actions without an agent tool stay in Pepper.

Connected clients shows who each connection acts for, its expiry and its last use. Expand a connection to see its permitted tools, saved drafts and recent approval states.

Limit the permitted work

A connection acts within the delegated user's current permissions and record access. It cannot add a permission that user lacks.

Active staff with a built-in or custom role can be delegates. Guests cannot hold agent connections.

The table lists every grant. A grant that reads make changes saves at once; the tool reference names the few tools that only prepare a proposal for review. The tool reference lists each tool with its grant and permission, and Steps that stay with people lists the steps that have no tool. The connection's grants and the user's permissions decide which tools it can call.

Preview and draft writes need invoices.manage. Customer search needs customers.view. Invoice approval needs invoices.finalize and access to that invoice.

Execution also needs invoices.manage. Keep both invoice permissions in a custom role that can approve and issue.

Preparing a project invoice reserves approved work and saves a draft. You still confirm issuance. With Projects · make changes, a client can record a project scope with its agreement reference and approve a completed milestone as its person, with confirmed: true. The project shows that the connection made the change.

People reads exclude private contact details, rates, time-off records and sign-in settings. Directory reads can include the person's work email.

See Roles and permissions and Modules.

Connect and review a draft

1. Ask the client to find a permitted customer.
2. Ask it to preview the invoice's exact totals.
3. Save the draft with a new idempotency key.
4. Open the returned document link in Pepper.
5. Check the customer, dates, lines, tax selection, currency and total.
6. Edit the draft if it needs a correction.

For EUR, a minor-unit price of "10001" with quantity "1.25" produces EUR 125.01 before tax. USD gives USD 125.01.

The draft shows Prepared through an agent connection, its connection name and the responsible user. Human edits keep that history.

You can use Review and issue in the app. A client that has execute access can request the separate approval below.

Approve one invoice

Approval permits the client to issue one document: an invoice, a quote, a pro forma or a credit note. Execution is a separate step. The same steps apply to a quote prepared for a deal.

flowchart TD
    accTitle: Approval and execution are separate
    accDescr: The client prepares a request. The delegated person approves or rejects it. Approval permits execution within the approval window. Only successful execution confirms issuance. Expired or stale requests need a new request and decision.
    request["`Client prepares
request`"] --> review{"`Delegated person
reviews`"}
    review -->|Reject| rejected["Rejected"]
    review -->|Approve issue| approved["`Approved
still unissued`"]
    approved --> execute["`Client executes
Pepper checks`"]
    execute -->|Checks pass| issued["`Issued number
confirmed`"]

Preparation and approval issue nothing. Respect a rejection. The client must execute within the approval window (10 minutes from preparation unless the owner changes it). Execution checks the request, draft and current access again. A refused execution does not issue the document.

The connection must have Invoices · execute after your approval. The delegated user must have permission to issue the document.

1. Ask the client to prepare an issue request for the saved draft.
2. Open the returned review link as the delegated user.
3. Check the connection name, customer, dates, tax and exact total.
4. Open Draft if you need to inspect its lines.
5. Return to the approval page.
6. Click Approve issue if the document is correct.

Click Reject to refuse the request. Approving gives the client permission to issue this document. It does not issue the document itself.

The page shows Approved; the agent can issue it now. The client must execute the approved request within its window. The owner sets the window in Settings > Agents, under Advanced > Approval window in minutes, from 5 to 1440 minutes.

The window starts when the client prepares the request. Approval does not restart it.

Issuing assigns the next number for the document type and freezes the document. It sends no email and records no payment.

After execution, the approval shows Issued. Check the document's assigned number before treating it as issued.

Approval rechecks the draft and connection. A failed check shows Out of date: the draft or the connection changed. Prepare a new request.

An Expired request also needs a new request and a new decision. A saved draft or an approved request does not prove issuance.

Stop access

To disconnect your AI app, open Connect your AI and click Stop beside it. The owner can stop any connection:

1. Open Settings > Agent connections.
2. Open Connected clients and find the named connection.
3. Click Revoke connection.
4. Read the consequence.
5. Confirm Revoke connection.

Open Advanced connection options to change the access switches. To stop all connections, clear Enable agent access. Click Save changes. Enabling access again does not restore revoked credentials.

To stop browser connections, clear Let MCP clients sign in through the browser. Click its Save changes button.

That switch revokes browser connections and their tokens. Pasted-credential connections stay active until their own expiry or revocation.

Expiry, user deactivation, permission changes that end their sessions or a changed application URL can stop access. An owner transfer stops every connection that acts as the former owner or the new owner. It also stops the connections and pasted credentials that the former owner made for other people. A connection that another person made for themself continues.

A request committed before revocation can finish. Later requests fail. Drafts, issued originals, approval history and request receipts remain.

When a call fails

A validation refusal names the fields to correct. Keep your input. A version conflict needs the latest draft before another update.

Use the same payload and key to retry an uncertain write. A successful identical retry returns its original result without another write.

For refused credentials, check expiry, revocation, the delegated user and the owner. Check HTTPS and host configuration if access is forbidden.

For a pending approval, wait for the person's decision. Do not treat Approved as Issued. Read the result after execution.

The client receives only granted tools. Its access may shrink after a role or module change. See the error reference.

Pepper keeps connection metadata, credential hashes, draft attribution and approval evidence on your server. Revocation does not erase that history.

A client can keep copies of records it read. Revocation cannot remove those copies. See Customer data and privacy.