Managing an organization — admin
0. Who is this documentation for?
What this doc covers
You are an admin of your organization. This page shows you what you control: teams, integrations, subscriptions, branding, OttoBot and agents.
Prerequisites
You are an admin of your organization.
More info
Getting people in, promoting and removing them is covered separately, as is everything to do with keys, credentials and credits. What members can already do without you is described in the end-user page.
1. What is yours, and what is HG's
| Who | What |
|---|---|
| Any member | Asking questions, running agents, seeing usage, inviting colleagues, creating their own key — and, though this page is framed as admin work, creating and deleting teams, connecting integrations, and creating subscriptions (editing one afterwards is limited to its creator and to admins). |
| You, as admin | Everything on this page, plus appointing admins and removing people. |
| HG only | Credits, which tool version you are served, whether a domain is recognized, and ownership of the organization. |
2. Teams
At Settings → Teams. A team is how people are grouped inside your organization; every organization starts with one default team. Note that creating and deleting teams is open to any member, not just admins.
| To… | How to do so |
|---|---|
| Create a team | Click Create Team, give it a name and, if you want, a short description. |
| Delete a team | From the same screen. The default team cannot be deleted, the attempt is refused. |
| Rename a team | There is no rename control in the Teams screen today, so in practice choose the name deliberately when you create the team. (The underlying API does permit renaming a non-default team; the default team's name is protected outright and cannot be changed.) |
| Put someone in a team | Covered in the access page, invitations are sent per team. |
A person can belong to more than one team, and removing them from one leaves them in the others. Removing the last admin of a team is refused, and if a removal drops someone's last access to the organization, their API keys for it are revoked at the same time. Where an organization does run several teams, note that changing a role or removing someone is gated by the team you are an admin of.
3. Integrations
At Integrations. Each integration is a data source that one or more tools depend on. If an integration is not connected, the tools that depend on it fail with an error naming what is missing rather than returning an empty result — this is the usual cause behind a missing_integration error.
Any member can connect or disconnect an integration, not only an admin. Disconnecting one disables every tool that depends on it, for everyone in the organization.
The screen lists the whole catalog next to whether your organization has it configured, so it is where you check what is connected; entries not yet open to you show as Coming Soon, with nothing to configure. It is not the answer to "why is this tool returning nothing?" — as above, a missing integration takes the tool out of your list or fails it with an error, rather than emptying its result. Connecting one means supplying its credential; removing one clears the credential and takes the dependent tools out of service. A saved credential is never displayed back to you on screen, so keep your own copy of anything you paste here — you can replace one, but you cannot read it off the screen to check it. For integrations that use a Phoenix-minted adapter key, disconnecting disables that key rather than deleting it, so reconnecting later resumes the same one.
Some integrations are provisioned for you when your organization is created, drawn from a managed set of eight and gated per-environment, so exactly which arrive configured varies. Anything not provisioned is either connected by you with your own credential or requested from HG. The keys and credentials guidance covers where each credential comes from.
4. Subscriptions
At Subscriptions. A subscription watches for a signal type and posts to a listener you nominate when it fires. Any member can create a subscription, but changing, enabling or deleting one is limited to whoever created it and to admins. Test fire is admin-only. Members also see only their own subscriptions in the list — the columns below describe the admin view.
| Column | What it tells you |
|---|---|
| Signal type | What is being watched. |
| Listener | Where the signal is sent. |
| Cadence | How often it is checked. |
| Status | Enabled or disabled. |
| Last fired | When it last sent something, blank means it never has. |
| Name | What you called it. |
| Deliveries (30d) | How many signals it has sent in the last 30 days. |
What you can do
| To… | How to do so |
|---|---|
| Create one | Click Create subscription, pick a signal type, and give it a listener URL. The URL must be HTTPS; anything else is refused. |
| Narrow what it watches | A subscription watches all accounts. The query field on the form configures the source, not what the subscription covers. |
| Check it actually works | Test fire sends a signal through. A message ending "delivery failed: …" points at your listener; "no listeners delivered" means nothing was attempted at all, which is a problem on the Phoenix side rather than yours. Note that test fire is admin-only, unlike the rest of this screen. |
| Turn one off without losing it | Toggle it. The subscription stays, disabled, and can be switched back on. |
| Rotate its secret | Enter a new secret to replace the old one. It is stripped from every response — the screen shows only whether one is set — so keep your own copy. |
| Change or remove one | Edit it, or delete it outright. |
If the screen says "No signal types available", no signal type has been registered for your organization yet. Connecting Exa under Integrations enables the Web News (Exa) signal type, and any member can connect it.
5. Branding
At Settings → Branding. A branding profile carries the colors used where your organization appears.
| To… | How to do so |
|---|---|
| Create a profile | Click New Profile and fill it in, or click Extract from Website to have the colors read from a domain. |
| Refresh one | Re-extract from Website pulls the colors again. |
| Change one | Edit the color fields — Primary, Secondary, Accent, Background Light, Text Primary, Text Body, Text Muted and Border — and click Save Changes. |
| Make one the default | Set as Default on a profile that is not already the default. |
Exactly one profile can be the organization default, and setting one clears the previous default. The default carries a badge in the list, cannot be deleted while it holds that status, and is the profile agents brand their output with when a run does not name another one.
6. OttoBot
At Settings → OttoBot, and only if your organization has OttoBot at all. Using the assistant is covered in the end-user page; this is its configuration.
| Section | What it controls |
|---|---|
| Constitution | The persona and standing instructions the assistant answers by. You edit these files directly, and OttoBot can propose a change for you to review before you confirm it. |
| Sub-agents | The specialized helpers it can hand work to, such as an account news researcher. Create them, edit them, and activate or deactivate one. Note the screen's own warning: deactivation is not a hard guarantee — if the store is unreachable when a conversation starts, a deactivated helper can briefly become available again. |
| Sessions | Past conversations and their transcripts, filterable by user. This is how you see what colleagues are actually asking it. |
| Analytics | Sessions, input and output tokens, and estimated cost over time, so you can tell whether it is being used and what it is costing. |
7. Agents, the admin side
Members can run agents, read their logs and open what they produce. Building an agent is not restricted to admins — any member of the organization can use the Builder, which is greyed out until your organization has at least one agent, unless you are already in the Builder view. Fork a blueprint from the Library first and it becomes active.
In the Builder you define what an agent does, which tools it may use, and which model it prefers, and you can give it sample output so colleagues can see what to expect before running it. What you publish there is what everyone in the organization sees in the Library.
One thing here is yours alone:
| To… | How to do so |
|---|---|
| Delete an artifact | From Artifacts, admins only. It removes every file that run produced. The run itself is kept, and the files do not come back. |
8. When to bring HG in
Three things sit with HG. None needs a formal process, a note to your HG contact is enough, and the first is worth sending before you need it.
| If you need… | Ask HG to… |
|---|---|
| More credits | Raise your limit. Do this while you still have headroom: on hard enforcement, a call is refused once its cost would take you past the limit — so the expensive tools stop first, for everyone, while credits still show as remaining — until HG lifts it (free lookups and cached answers continue, and nothing clears on its own); on soft enforcement nothing is blocked but overages may be charged. Watch your usage page and ask at around 75%. |
| A colleague's domain recognized | Confirm the domain, so they can sign up. |
| The newest tools, or tool names that match the documentation | Confirm which version your organization is on, and move you if you are not on the latest. |
9. Accessing the admin tools
The admin tools let you drive organization administration — inviting and removing people, reading consumption, and managing integration credentials — from a connected client instead of the screens. They are available only to org admins, through an admin-scoped key. Each one is documented tool by tool in the Admin section of the MCP tools reference, which is the place to look for exact inputs and outputs.
An OAuth connection never has the admin tools. There are two ways to connect a client, and only one of them works here:
Signing in (OAuth), the Authorize screen you get when a client offers to connect. Convenient, but the access it grants is always member-level, whatever your role, and no admin tool will appear in that client. This is the default, so it is what you get unless you deliberately do otherwise.
Endpoint address + admin API key, the only way to reach the admin tools. Configure the client with the endpoint address and an admin key, instead of signing in.
The two levels do not mix. While you remain an org admin, an admin key sees only the admin tools, not the company and contact tools. If you want both, keep two connections and use whichever fits the task.
You need an admin key
| Step | How to do so |
|---|---|
| Create the key | Click MCP in the sidebar, then create a key and set its scope to Admin. The Admin option is selectable only if you are an org admin — it is greyed out otherwise, and a request that reaches the server anyway is refused with "Only org admins can mint admin-scoped API keys." A non-admin cannot mint one. |
| Copy it | Copy it when it appears. It also stays visible in the key list on the same page, so you can come back for it. |
| Connect your client with the key | Use the endpoint address shown on the same page, together with the key. |
Same rules, wider reach
The tools, the screens and the REST facade share the same underlying services, but their permission checks are not identical, so do not assume an action behaves the same way in both places. The admin tools always require an admin-scoped key held by a current admin. Several screens are deliberately more open than that — connecting or disconnecting an integration, for instance, is available to any member on screen while the equivalent admin tool refuses a non-admin key. What also differs is reach: listing every key in the organization with its owner and last use is practical only through the tools. Per-key consumption, including keys since rotated away, is on the usage screen too.
Two things to expect
| What happens | |
|---|---|
| The key follows your role, not the other way round | A user counts as an org admin while they hold an admin role on at least one team. Once that is no longer true — but they are still a member — the key is not revoked: over MCP and Power Automate it is treated as an ordinary user key, while the admin REST endpoints reject it. If they lose access to the organization altogether, every key they hold for it is revoked and stops authenticating. |
| There is no bulk action | Each tool handles one person, or one credential, per call, so doing something for fifty people means fifty calls. Inviting the same address twice is safe: it returns the invitation already in flight rather than sending a second one. |
10. Error codes
The MCP admin tools and the REST facade return stable machine codes alongside their message, so a failure is scriptable. The screens do not — they surface a human-readable message instead, so do not key a script on a code you saw in the UI.
| Code | Meaning |
|---|---|
already_member | Already an active member. |
disposable_email | Domain is blocklisted. Invitation does not bypass domain rules. |
last_admin / cannot_remove_owner / cannot_remove_self | Structural refusals, not errors. |
user_not_found / invalid_user_id | No active membership, or a malformed id. |
org_misconfigured | The organization has no default team, which is a server-side fault rather than anything you did. Send this one to HG. |
integration_not_found / integration_disabled | Unknown integration key, or one not available for configuration. |
invalid_credentials / tool_setup_failed | The credential failed validation, or the setup that follows it failed. |
adapter_key_disable_failed | The credential was removed, but the key behind it could not be disabled. The integration is off; something is left behind. Report it. |
key_not_found | No such key, or nothing has been charged to it in your organization. |
org_not_found | Your organization has no resolvable consumption status. The organization is taken from your key, not from the request, so this is not a bad parameter — report it. |
validation_error | The request itself was malformed. Check the parameters before looking anywhere else. |
forbidden_admin_scope | The key is not admin-scoped, or its owner is no longer an org admin. |
invalid_range / range_too_large | A consumption query with a bad date window, or one longer than the maximum allowed. |
invalid_cursor | A list request carried a malformed paging cursor. |