Keys, credentials and consumption — admin
0. Who is this documentation for?
What this doc covers
You need a key, a credential, or an answer about what your organization is spending. This page shows you the keys it issues, the credentials it holds, and what they consume.
Prerequisites
You are an admin of your organization. Much of what follows is not admin-only, though: creating your own user key, connecting or disconnecting an integration, and reading the usage page are open to any member. Only minting an admin-scope key and using the admin tools require the role.
1. API keys are self-serve
This section is about one thing only: the key that connects a client to HG MCP Server. Not the credentials behind the tools. Those are different, they are covered in section 2, and most of them are HG's rather than yours.
What this key is for
It is what proves who you are when something outside the app talks to HG MCP Server. This is the key that goes in the connector configuration in your LLM, the JSON where you declare the HG MCP Server connector. The MCP page gives you a ready-made address with the key already embedded in it — copy that whole URL into the connector rather than assembling it yourself. The same applies to a script or anything else calling the tools directly. Working inside the app does not need one, the app already knows who you are.
| Key | Scope | What you use it for |
|---|---|---|
| Your everyday key | user | Reaching HG data: firmographics, technographics, intent, spend, contacts, and the rest of the company and contact tools. This is the one almost everybody should hold. |
| An admin key | admin | Managing the organization from your LLM: inviting and removing people, setting integration credentials, reading consumption. It sees none of the HG data tools, so it cannot replace the key above. Keep both as separate connections. See Before You Get Started → Admin for reaching the admin tools. |
That HG MCP Server key is self-serve. Create one for yourself under MCP in the sidebar. New keys are user scope by default.
| Task | How | What to know |
|---|---|---|
| Create a key | Click MCP in the sidebar, then Generate New Key. Give it a name, leave the scope on User, and create it. | Copy it when it appears. It also stays in the key list on the same page, so you can come back for it. The endpoint address your client needs is on that page too. |
| Check a key without spending anything | Click MCP in the sidebar and read the key list, or make a tools/list call | The key list shows each key's name, the key, the MCP endpoint, when it was created and when it was last used, and an actions column. An admin-scope key carries an Admin badge beside its name. Keys Phoenix manages for you — the one an OAuth sign-in provisions — appear here too, but read-only: a masked prefix, Managed via OAuth — no manual endpoint, and nothing to copy or revoke. Last Used is derived from activity, not from authentication — specifically from tool calls that succeeded, at any credit cost, cache hits included, and from agent runs that succeeded. So a key whose every call failed still reads Never, and the tools/list check below never registers there either. A tools/list call authenticates end to end without spending anything, since credits are charged only when a tool actually runs — so it proves the key works, but look at the call's own result rather than at Last Used. |
| Rotate a key | On MCP: Generate New Key, move your client onto it, then Revoke the old one from the same list | There is no rotate action. Rotation is those three steps in that order, and it needs no downtime. |
| Create an admin key | Click MCP in the sidebar, then Generate New Key, and set the scope to Admin | The separation is strict both ways: an admin key sees only the admin tools, a user key only the data tools. Admin powers follow the person, not the key. 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 and its admin tools stop working: the admin REST endpoints and the Power Automate facade return 403 forbidden_admin_scope for the admin tools, while over MCP those tools simply disappear from the tool list. Over MCP and Power Automate the key itself keeps working, falling back to user scope. If they lose access to the organization altogether, every key they hold for it is revoked. The check runs on every request, so a role change takes effect at once and there is nothing to rotate. Most people should hold a user key. |
Removing someone revokes their keys, but confirm it. Revocation happens automatically once the person loses access to the organization — removing them from a single team while they remain in the org revokes nothing. It is also not guaranteed: if it does not succeed the removal still goes through and you are not told. To confirm, use the admin_list_api_keys admin tool, which lists keys across the organization with their owners — the MCP page in the sidebar shows only your own keys, never a colleague's, so it cannot answer this. Pass include_system_managed: true: the keys an OAuth sign-in provisions are system-managed and the default call leaves them out, which is precisely the set an offboarding check is looking for. It returns 100 keys per page by default, and up to 500 if you ask for more.
2. Integration credentials
Set at Integrations. A saved credential is never displayed back to you on screen, so you can replace one but not read it off the screen to check it.
The model credential is the one that runs out. Most of what follows either arrives connected or is yours from the start; the exceptions are the four in Not everything is connected below. The seeded model credential is a starter allowance, so plan to replace it with your own before it is exhausted: when it runs dry the assistant stops answering and so does anything that runs an agent, while the HG data tools themselves keep working.
| Credential | Where the value comes from | What that means for you |
|---|---|---|
| The LLM key | HG to start with, then you. | This is what pays for the assistant that reads your question and decides which tools to call. It arrives with a starter allowance so the product works out of the box. Once that is spent, supply your own and set it here. |
| The HG MCP tool keys | HG. | The credentials behind the HG data tools, firmographics, technographics, intent, spend and the rest. Most arrive connected when your organization is created and there is nothing for you to supply. Some are granted on request instead — see Not everything is connected below. |
| Third-party keys | You, from the start. | Services you hold your own contract with. Set the credential here; it is stored encrypted and is not shown back to you on screen. |
Which ones are available
For the LLM key, the seeded provider is OpenRouter, and OpenAI can be configured instead. Through OpenRouter you get whatever models that provider carries; the picker in the Playground puts the usual ones first: Claude Sonnet 4.6 (the default), Claude Sonnet 4.5 and Haiku 4.5, OpenAI o3 and o3-mini, GPT-5 mini and nano, GPT-4o and GPT-4o mini, and Google Gemini 2.5 Pro, 2.0 Flash and 2.0 Flash Lite. The picker reflects what the provider is carrying, refreshed about once a day, so a model can drop out of the list without notice and one already withdrawn can linger in it for up to a day. Whichever you choose is charged to the credential set here, so a more expensive model spends the allowance faster.
For third-party keys, the ones you supply from your own contract, the catalog covers connectors such as Snowflake, Slack, Microsoft Teams and Exa, alongside others. The Integrations screen is the list to read, not this page.
The Integrations screen is the authoritative list. It shows the whole catalog next to whether yours is configured, and it changes as connectors are added. Entries that are in the catalog but not yet open to you show as Coming Soon with nothing to configure — so read availability off that screen rather than from this page.
Replacing the model credential with your own
Do this before the starter allowance runs out, not after. The change takes effect on the next question asked, and there is no downtime.
| Step | What to do |
|---|---|
| 1. Get a key from the provider | Create one in your own account with the model provider, and give it a spending limit there. That limit is now the only thing bounding what the assistant can cost you, so set it deliberately. |
| 2. Open Integrations | Find the model integration in the list. It will already show as connected, on the seeded credential. |
| 3. Paste the new value and save | This replaces the old one. Neither value is shown back to you on screen, so keep your own record of which key you used. |
| 4. Ask a question in the Playground | This is the only check there is: the value is stored as you typed it, without being validated against the provider, so saving successfully tells you nothing about whether the key is good. If it answers, the credential works. If it fails, a wrong or expired key is the first thing to suspect — but the failure does not confirm that, so re-read the value you pasted rather than pasting the same one again. |
Two things worth knowing. Replacing it is a straight swap, there is no second slot and no fallback to the seeded credential once you have overwritten it. And this credential is shared by the whole organization, so everyone's questions draw on the spending limit you set.
Not everything is connected when your organization is created
A new organization arrives with most integrations already connected, but four are deliberately left out. This is by design, not an oversight: each is withheld for its own reason, and the tools that depend on them will not return results until they are connected.
| Integration | What depends on it | What happens when you ask |
|---|---|---|
| Apollo.io | Contact enrichment | Granted case by case. It carries a cost to HG, so expect to be asked what you need it for. |
| HG Insights DB Query | Direct queries against HG data | Granted case by case. Expect a conversation rather than a switch being flipped. |
| HG Insights Cloud Dynamics | Cloud spend and dynamics data | Granted on request. |
| TrustRadius Product Data | Product reviews and product-level detail | Not granted. This data is served another way now. |
| Anything else | — | Most integrations are already connected. If one is genuinely missing, that is worth reporting as a fault rather than a request. |
TrustRadius Intent is a different integration and is connected by default. Only the product-data one is not.
When to ask
Ask when a tool that should work does not. The signs are consistent:
| What you see | What it usually means |
|---|---|
| A tool returns nothing, repeatedly, for input you know is good | Usually the data genuinely is not there for that input, because a missing integration normally takes the tool out of your list or fails it with an error naming what is missing. The exception is a broad tool that gathers several things at once: it stays listed, and a section whose integration is missing is simply left out of the answer, silently. If part of a result is always absent, treat that as a missing integration rather than missing data. |
| An error naming a missing integration | The same thing, said explicitly. |
| A tool is in the reference but not in your client's list | Check the key's scope first: an admin key shows only admin tools and a user key only the data tools, so the commonest cause is simply the wrong key on that connection. Otherwise the integration behind it is missing, or your organization is on an older tool version. Say which tool you expected. |
Send your HG contact three things: which tool, what you were trying to do, and the exact error if there was one. That is enough to identify the integration; you do not need to work out which one it is.
Ask before you need it, if you can. None of these is instant, and two of them involve a decision on our side rather than a configuration change.
3. Observing consumption
What you can see, and where
Consumption is visible in three places, each answering a different question.
| Where | What it answers |
|---|---|
| Settings → Usage | The whole organization at a glance. Every member can open it, not just you. |
| Settings → Teams, then a person in the member list | What one person has been doing. |
| The admin tools, from a client with an admin key | The sharper cuts the screens do not offer. See User management for the exact inputs and outputs. |
The usage page
| What you see | What to do with it |
|---|---|
| Credits used, the limit, and what is left | The headline. Read remaining, not used. This counter runs from the last time HG started a new period for you, not from a date that rolls over on its own — see The credit limit below. |
| Daily usage, last 30 days | Where a spike shows up. A single day out of line usually means one workload, not growing adoption. |
| Usage by tool | Which tools the credits went to. Some bill per result rather than per call, so a broad query can dominate this. |
| Usage by authentication source | Whether calls arrived on an API key or through an OAuth connection — a split by credential type, not by app versus connected client. A key Phoenix manages for an OAuth user counts on the OAuth side, and a few rows it cannot classify sit outside both filters, visible only under All. The table underneath is what attributes a runaway workload: a row per key or OAuth client with a Creator column, so a live key maps to a person and this is how you find who to talk to. A key that has since been deleted appears as Deleted API key with its Creator shown as Unknown — the link to its owner is gone, which is exactly the offboarding case, and why the admin tool below is the better instrument for it. Read Unknown carefully, though: OAuth traffic that is not tied to a key shows it too, so an Unknown row is not by itself evidence of a departed colleague. |
| Cache performance | Hit rate and the credits it saved you. Cached results cost nothing, so a healthy hit rate is consumption you are not paying for. Avg Response Time sits alongside it — whether calls are slowing down, which is not a cost signal but lives here. |
One person at a time
Open Settings → Teams, find them in the member list and open their usage. You get their tool invocations, conversations, agent runs and agent credits, their success rate, when they last ran an agent and whether it succeeded, and when they were last active, alongside the teams they belong to and a paginated feed of their recent activity. This is the view to use before a conversation about someone's consumption, rather than inferring it from the key breakdown.
What the admin tools add
The usage page already attributes consumption per key and labels keys that are gone as Deleted API key, so that much is on screen for any member. A few things go beyond it. All of them need a client connected with an admin key, which is section 1.
| Question | How |
|---|---|
| What did a key that no longer exists consume, precisely? | The per-key consumption tool can recover the key's original name, which the screen never does — there it is only Deleted API key with an Unknown creator. It manages this when the name was recorded alongside the usage at the time; where it was not, the tool falls back to Deleted API key as well. It also returns an explicit deleted flag and counts billable usage only, where the screen includes an unattributed bucket. This is the sharper answer to "what burned the credits last month?" after an offboarding or a rotation. |
| What did one person consume over a window I choose? | The per-user consumption tool takes a user and a date range, up to 366 days, rather than the fixed periods on the screen, and breaks that user's usage down per tool. A separate per-key tool does the same for one key. |
The admin tools also report each person's lifetime credit usage and how many keys they currently hold — figures the on-screen member list does not show — which is the quickest way to spot an account worth looking at. The key count is of live keys only: revoking one removes it from the count, and keys Phoenix manages for them are not included.
4. The credit limit
Credits are the unit of consumption, and the limit is the ceiling for the whole organization. It is shared: everybody draws on the same balance.
| Default | |
|---|---|
| Credit limit | 100 credits when the organization is created, unless your contract says otherwise. |
| Plan | The free developer plan, unless you were set up on something else. |
| Enforcement | Hard. A tool call is refused when its cost would take you past the limit, so the expensive ones stop while credits remain; free lookups and cached answers keep working. Only HG can lift the block. |
| Billing period | The dates shown on the usage page. Note that the headline credits figure is not recomputed from them — it is a running total that only HG resets. The panels below it are windowed: daily usage is always the last 30 days, while the by-tool, by-source and cache panels look back to the start of your period, capped at 366 days. On an organization that has never been reset, the headline can therefore cover more time than any panel can show, and the two will not reconcile. |
Hard enforcement is a wall, not a throttle. A call is refused as soon as its cost would carry the organization past the limit — so the expensive tools stop first, for everyone, while the balance still shows credits left and before the usage page turns red. Retrying will not help. Nothing degrades gracefully and nothing queues. Free lookups and answers already in the cache continue, so the app will not feel completely dead — do not read that as the limit not having been reached. The block does not clear on its own. Both the tool error and the red banner on the usage page say to wait for the billing period to reset; nothing rolls the counter over automatically, so disregard that in both places. Only HG can lift it, by raising your limit or starting a new period for you. Contact your HG representative. (The same tool error tells you to ask your administrator to raise the limit — an admin cannot.)
How you are warned
Alerts fire at 50 / 75 / 90 / 100%, by email, to the owner and the admins. The usage page also shows a red block once the limit is exceeded, though only on hard enforcement; on soft enforcement you get an Over Limit badge instead.
The useful moment to act is the 75 to 90% band. Ask before the block, not after it.
Asking for more
Only HG can raise the limit. There is no screen for it on your side, and no request form: contact your HG representative. They can raise it within whatever your contract allows.
Tell them what you are at, what you need, and why the consumption changed. The usage page gives you all three: current usage against the limit, the daily view showing when it moved (the last 30 days, which may be shorter than your billing period), and the breakdown by tool and by key showing what caused it.
It is not instant, and once you are over the limit the credit-consuming tools are already stopped — with no automatic reset to wait for. That is the argument for acting on the 75% alert rather than the 100% one.