Developer Hub
Asha, operations lead at Acme Support, wants to connect other systems and AI tools to her Perfox workspace:
- Server-to-server REST calls — her order system uploads product manuals into the knowledge base and pulls conversation transcripts every night.
- MCP clients — her team wants to use the workspace's tools straight from Claude, ChatGPT or Cursor.
- Background job health — she wants to see that her email inbox listener and her nightly knowledge-base sync are still running.
The Developer page (Admin → Developer, /developer) covers all three in three tabs: API keys, MCP and Scheduled Jobs. Each tab has its own link (/developer?tab=keys, ?tab=mcp, ?tab=scheduled-jobs). The page appears for members with the View settings permission; creating, rotating or deleting keys, changing a key's permissions, generating a Claude skill and revoking a connected client need Manage settings. An old link to /settings?tab=api_keys brings you here.
1. API keys

Each key carries a least-privilege set of scopes and works for both the REST API and the MCP server.
Connection details
The Connection card at the top of the tab shows where your keys are used:
- API base URL —
https://<your-workspace>-api.perfox.ai/api/v1, the base of every REST endpoint. - MCP server —
https://<your-workspace>-api.perfox.ai/mcp, for MCP clients.
Each has a Copy button, and REST API reference ↗ opens the full endpoint list. Send Authorization: Bearer sk_… to either URL.
Creating a key
- Click + New key.
- Enter a Name (for example
production-webhook). - Tick the Scopes the key needs — the heading shows how many are selected. You can only give a key permissions your own role has; the others are greyed out ("A key can only have permissions your own role has."). Create key stays disabled until the key has a name and at least one scope.
- Click Create key. The API key created dialog shows the full key with Copy and Copy as an Authorization header.
Copy the key now
The full key is shown once. Perfox keeps only a fingerprint of it, so it can't be shown again or copied later. If you lose a key, rotate it.
Managing keys
Each row shows the key name, an active badge, the masked prefix (sk_••••), a scope summary (for example "16 scopes · documents, knowledge base, …") and when it was last used ("Never used", "Used 3 mins ago"). Click the scope summary to see the key's permissions. The ⋯ menu offers:
- Permissions — view and change what the key can do (see below).
- Rotate — issues a new secret for the same key (name and scopes unchanged). The old secret stops working immediately, and the API key rotated dialog shows the new one, once. You can't rotate a key that carries a permission your own role doesn't have.
- Delete — permanently deletes the key after a confirmation. Any integration still using it starts getting
401errors.
If something goes wrong, an error message pops up.
Changing a key's permissions
You can change what a key is allowed to do without replacing it — the key, its name and its secret stay the same, so nothing needs to be redeployed.
- Open the key's ⋯ menu and choose Permissions (or click its scope summary).
- The dialog shows the same grouped checkboxes as + New key, ticked with the key's current permissions. Tick or untick what you need.
- Click Save permissions (enabled once something changed and at least one permission is ticked). A message confirms how many permissions were added and removed.
The change applies to the key's next request: a permission you remove makes the next call that needs it fail with 403.
You can only give a key permissions your own role has. If a key already has permissions your role doesn't, the dialog shows them read-only ("This key has permissions your role does not …, so only someone who holds them can change it."). If someone else changed the key while you were editing, saving is refused and asks you to reopen it.

Keys managed by an app. When you enable a marketplace app that connects to your workspace, it gets its own key. That key shows a Managed by … badge, and its ⋯ menu offers:
- Open the app (for example Open CRM ↗) — opens it in a new tab, signed in with your Studio session.
- View permissions — a read-only list of what the app's key can do. The app needs exactly these; new ones arrive with a platform update, so they can't be edited here.
- Manage subscription — the app's page under Apps.
An app's key can't be rotated, deleted or re-scoped here — it's removed when you cancel the app.
Scope catalog
| Group | Scopes you can grant |
|---|---|
| Agents | Read agents · Create & edit agents · Publish agents |
| Knowledge Base | Read Knowledge Base · Upload & manage Knowledge Base |
| Customers | Read customers · Create & update customers |
| Conversations | Read conversations & transcripts · Write conversations |
| Credentials | Read provider credentials · Register provider credentials |
| MCP Servers | Read MCP tool servers · Register MCP tool servers |
| Documents | Structured document extraction |
| Analytics | Read analytics |
| Support | Read support tickets · Raise & reply to support tickets |
| Webhooks | Read webhook subscriptions · Manage webhook subscriptions |
A new key starts with Structured document extraction, Read Knowledge Base and Upload & manage Knowledge Base ticked — untick anything you don't need. Full admin access can never be granted to a key. The API reference lists which endpoints each scope unlocks.
Send the key on every request as:
http
Authorization: Bearer sk_...2. MCP server
The MCP tab turns your workspace into a Model Context Protocol (MCP) server. Claude, ChatGPT, Cursor, the MCP Inspector and any other MCP client can discover and use your workspace's tools — the same tools as the REST API.

The MCP server card shows:
- Server URL —
https://<your-workspace>-api.perfox.ai/mcp, with a Copy button - Transport — Streamable HTTP; Method — POST
- Tools — how many tools are currently available
- Open MCP Explorer ↗ and REST API reference ↗ links
Under Connect, pick how your client authenticates.
Connect with OAuth 2.1 (recommended)
Choose OAuth 2.1. There is no key to paste — the client registers itself automatically:
- In Claude: Settings → Connectors → Add custom connector (ChatGPT: Settings → Connectors; Cursor / MCP Inspector: add an HTTP server).
- Paste the Server URL. Leave Client ID and Client Secret blank.
- A Perfox sign-in page opens — sign in with your workspace email (magic link) and approve access. If you use two-step verification, enter your code in the Studio first; approval is refused until you do.
- The workspace tools appear in your client.
The connection acts with your own role's permissions, so every team member signs in as themselves.
Connect with an API key
For a client that can't open a browser sign-in, choose API key and send a key from the API keys tab as a bearer token on every request:
http
Authorization: Bearer sk_...A key is shown only once, when you create or rotate it, so keep it where your client's configuration lives.
Don't put the key in the URL
Adding the key to the address (?key=) is deprecated: addresses end up in server and proxy logs. Existing connections that do it still work for now, but the server marks every such request as deprecated. If your client can't set a header, connect with OAuth instead.
Connected MCP clients
Below Connect, Connected MCP clients lists every client a team member connected with OAuth. Each acts as that member, with their role's permissions. A row shows the client's name, an active or expired badge, the member's email, where the client signs in from, and when it was authorized, last given a token and when its access expires.
Click Revoke to cut a client off. It loses access as that member immediately: its next call gets a 401, it can't refresh, and reconnecting needs the member to sign in and approve it again. Deleting a team member on Users ends their connections the same way. With no connections yet, the list reads "No connected clients".
Send to Claude
The Set up in Claude in one step card has a Send to Claude button. It generates a Claude Skill preloaded with your workspace's tools and docs, plus a new API key made just for it:
- Click Send to Claude, then Generate skill. The new key is named "Claude skill" with today's date and carries the default key scopes your own role holds.
- Click Download .zip (or Copy SKILL.md).
- In claude.ai → Settings → Capabilities → Skills, click Upload and choose the .zip. For Claude Code, unzip it into your project's
.claude/skills/folder.
The new key then appears on the API keys tab, where you can rotate or delete it like any other.
3. Scheduled Jobs
The Scheduled Jobs tab lists the recurring jobs and subscriptions registered for your workspace, with when each runs next, how often, and any error. Click Refresh to reload.

| Type | What it is |
|---|---|
| The inbox listener for an email connection that receives mail — for example a Microsoft 365 mailbox subscription (renewed automatically) or a Gmail / IMAP mailbox check. | |
| KB Sync | A knowledge-base connector sync — OneDrive / SharePoint, Google Drive, S3 or a website crawl — on its schedule. |
| Schedule | An agent's Schedule trigger or folder watch. |
Columns: Type, Name (with a detail line such as the connector or provider), Frequency (for example every 6h or a cron expression like 0 0 * * *), Next run, Last run, Status (active, pending, error, disabled) and Last error. A folder watch that had to skip a file keeps running and shows that note under Last error.
Two extra red badges flag jobs that need attention:
- not scheduled — the job is recorded but not actually registered to run, so it will never fire.
- orphaned — the job runs but nothing owns it any more.
If the list can't be loaded, the tab says "Could not load scheduled jobs" and offers Try again. With nothing registered it reads "No scheduled jobs or subscriptions registered yet."
Worked example: using Acme Support's tools from Claude
Setup: Asha opens Admin → Developer → MCP and copies the Server URL, https://acme-support-api.perfox.ai/mcp.
Action: In Claude she opens Settings → Connectors → Add custom connector, pastes the URL, and leaves Client ID and Client Secret blank. A Perfox sign-in page opens; she signs in with her work email and approves access.
Result: Acme Support's workspace tools — the same set the REST API offers, such as knowledge-base search, agents, customers and conversations — appear in Claude. She asks, "What does our returns policy say about opened items?" and Claude answers from the knowledge base. Back in the Studio, Claude now shows under Connected MCP clients with her email.
What just happened: Claude registered itself with the workspace, Asha signed in as herself, and every tool call runs with her own role's permissions — no shared key involved. If she ever needs to cut Claude off, Revoke on that row does it immediately.
For a headless script, she would instead create a key with only the scopes it needs and send it as an Authorization header.
Good practice
- Grant only the scopes a key needs. Create separate keys for separate integrations so you can rotate or delete one without affecting the others.
- Store a key the moment it's shown — it can't be displayed again.
- Rotate keys periodically — Rotate keeps the name and scopes, so nothing else needs reconfiguring.
- Prefer OAuth for personal tools such as Claude, ChatGPT or Cursor, so actions carry each person's own permissions — and review Connected MCP clients from time to time.
- Send keys in a header, never in the URL.
- Check Scheduled Jobs after connecting a mailbox or a knowledge-base source, and whenever inbound mail or syncs seem to stop.