Who can use a credential

Choose who may use each saved key: Only you, One team, or Everyone in your organization. For example, keep a test key personal and share a production key with the team that runs your support agents.

Change who can use it

1. Open Credentials and click the credential.
2. Click Change next to Who can use it.
3. Choose Only you, One team, or Everyone. For one team, select the team too.
4. Save the change.

Only you is available when your organization allows personal keys. Admins control this under Settings → Organization → Personal keys. A model provider’s key opens its connection under Models, where the same sharing control is on its Settings tab.

Give an agent access

An agent sometimes works for nobody in particular: a message on one of its channels from someone other than its owner, or a run that acts as the agent itself. Then it can use only the accounts given to the agent.

Open the agent and, on its Overview tab, find the Access card. It lists every account its tools and settings use that it has not been given yet. Click Let this agent use … next to one to give it. Nothing is given without that click.

When it has no access to an account a tool needs, the tool answers “I don’t have access to HubSpot Companies” and the agent tells the person so, instead of answering as if it found nothing.

Organization rules

Admins manage service restrictions, expiry, rotation and other credential rules in Settings. Sharing decides who the credential belongs to; organization rules can further limit its use. When a run is refused, it receives the reason.

Detailed grants to people, roles, agents and workspaces remain available through the API below.

For developers

Principals.

user, team, role and agent are identity-shaped; a workspace is a run location. A workspace can be a grant target but never owns a credential.

Grant budgets. A grant can also carry a spend budget of its own (budgetId), set through the API.

Permissions. use allows resolving the secret for a run; manage adds listing, adding and revoking grants on the credential. Admins and owners hold connections:manage, which bypasses team-visibility and grants on organization credentials but does not reach personal ones.

One grant exists per credential and principal; granting again refreshes its permission, budget and expiry in place. An expired grant counts as absent. A grant’s own spend budget is stored and returned, and enforced at resolve time by the Enterprise governance module. Deleting the credential removes every grant on it.

Refusal reasons: no grant on this org-scoped connection, no grant on this user-scoped connection, not a member of the connection team. A refused run fails with CONNECTION_NOT_GRANTED and the reason.

Granting checks the target: a user must be an active member of the organization, a team must exist in it, a role must be one of the four built-in roles, an agent or workspace must exist in the organization, and a budgetId must belong to it. Without connections:manage, an actor may only bind a credential to an agent they created or a workspace they own.

Grants are managed with the same three operations (list, add with principal type and id plus optional permission, budget and expiry, revoke) on the Credentials API. Granting and revoking write connection_grant and connection_revoke_grant to the audit log with the principal, permission, budget, expiry and how the actor was authorised. A revoke takes effect at once on the instance that handled it and within 30 seconds on any other; expiry is evaluated on every use.

Each use writes one connection_resolve audit row: who asked (user, agent, workspace), which credential, the run and purpose, and how the decision was reached (owner, connections:manage, or the grant that carried it). Jobs without a user (schedulers, the deployment reconcile loop) resolve organization credentials for the organization; a personal credential only with its owner as actor, or through a grant to the run’s agent or workspace.