Skip to main content

API keys and their permissions

An API key lets an AI agent, a script, or your own tooling use HyperView. Its access rules decide which systems it can reach, and a capability policy decides what it may do on them.

An API key lets an AI agent, a script, or your own tooling use HyperView. Its access rules determine which systems it can reach, and a capability policy determines what it can do on them.

Before you start

  • An admin role.

  • A decision about which systems the key needs, and how much it should be allowed to do there.

Step 1 - Choose the type and name

  1. Go to Admin > API Keys and click Actions > Create key.

The Create API Key panel with Type, Name, Owner, Expires and System access numbered 1 to 5

  1. Type: Automation for AI agents and scripts that drive systems, or Remote support links for tooling that creates DesktopAgent links.

  2. Name: must be unique. Name it after what uses it.

  3. Owner.

  4. Expires: Never expires, or a date.

  5. System access: set in Step 2.

Step 2 - Choose which systems it can reach

API key access rules with systems, policy, reorder, remove, Add rule, Guardian context and Action log level numbered 1 to 7

  1. Which systems the rule covers: Owner's systems, Owner's folders, Folders or Systems. A folder includes its sub-folders.

  2. The capability policy for those systems, for example Approval for risky. See Create and use capability policies.

  3. Move a rule up or down.

  4. Remove a rule.

  5. Add rule: for a group of systems that needs a different policy.

  6. Guardian context: optional instructions for Guardian when it reviews this key's requests. See Secure the account.

  7. Action log level: can raise how much this key's activity is logged, but never lower it.

NOTE: Rules are checked top to bottom, and the first rule that matches a system wins. Put the narrowest rule first. A key with no rules can't reach anything, and it can't see systems no rule matches.

Step 3 - Copy the key

  1. Click Create.

The API Key Created dialog with the one-time warning, API key and account UUID numbered 1 to 3

  1. The key is shown once only.

  2. API Key: copy it now.

  3. Account UUID: tools such as the hv CLI need this as well.

NOTE: If you lose the API key, you can't get it back. Create a new key and update whatever used the old one.

See what a key has done

Troubleshooting

  • ERR_INVALID_API_KEY_CREDENTIALS: wrong account UUID or key.

  • ERR_API_KEY_DISABLED or ERR_API_KEY_EXPIRED: the key is deactivated or past its expiry date.

  • ERR_API_KEY_NAME_NOT_UNIQUE: another key already has that name.

  • The key can't see a system. No rule matches that system. Check its rules.

Related articles

Did this answer your question?