API keys and scopes

https://docs-dev.evohub.io/mcp

claude mcp add --transport http evohub-docs-docs https://docs-dev.evohub.io/mcp

{
  "mcpServers": {
    "evohub-docs-docs": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://docs-dev.evohub.io/mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "evohub-docs-docs": {
      "url": "https://docs-dev.evohub.io/mcp"
    }
  }
}

{
  "servers": {
    "evohub-docs-docs": {
      "type": "http",
      "url": "https://docs-dev.evohub.io/mcp"
    }
  }
}

An API key lets a script, CI job or another system call the EvoHub API without a person signing in. Each key carries scopes: the exact permissions it has. This page explains the two kinds of key, how to create and revoke them, and their limits.

#Two kinds of key

Both kinds work in one organization only, and both use the same headers. See API overview.

#Create a personal key

A key with no scopes can authenticate but is refused everywhere. That is the safe default, not an unrestricted key.

A personal key is always a slice of you, measured at the moment it is used. If your own permissions shrink, for example because an administrator changed your role, the key loses those permissions too. If you leave the organization or delete your account, the key stops working.

#Create an organization key

An organization key's scopes are its role's, read live. Edit the role and every key on it changes; delete the role and every key on it stops working.

#Scopes

Scopes are the same permissions roles are built from. They are grouped by product:

What each permission covers is described in Roles and permissions.

Give a key the fewest scopes it needs. A key that only reads monitors needs uptime:monitor:read and nothing else.

#What a key can never do

API keys are for automation, and some actions are reserved for a person signed in to the console.

• A key never counts as an administrator. Owners and Admins pass every check when they act in person, but a key is held to its scopes, even if it was created by an Admin or carries the Admin role. A key never sees another team's work just because its creator could.
• A key cannot approve or review. Approving or requesting changes on docs change requests and changelog drafts, and merging or reverting a docs change request, must be done by a person. So must connecting a docs site to GitHub and issuing access credentials for a private docs site. A key that tries gets 403 PERSON_REQUIRED.
• A key cannot act on a person's own account. It cannot switch organizations, create an organization, change a profile or password, manage sessions, two-factor authentication or connected accounts, accept invitations, or delete an account. These return 403 API_KEY_NOT_ALLOWED.
• A key cannot manage API keys. Creating, listing and revoking keys, of either kind, is done in the console.
• An organization key cannot send invitations, because an invitation names the person who sent it. Use a personal key with identity:user:invite.

#Revoke a key

Revoking stops a key immediately, and anything still using it starts failing at once. It cannot be undone.

• Personal key: in My Account → API Keys, select Revoke on the key's row and confirm. You can revoke your own keys in any organization.
• Organization key: in Organization → Organization Keys, select Revoke on the key's row and confirm. This needs the Organization Keys → Write permission.

Your My API Keys list shows each key's prefix, organization, scopes (hover the count to see them), state (active, revoked or expired), when it was last used and when it expires. A key that has never been used shows Never under Last used, which makes unused keys easy to find and revoke.

#Related

• API overview
• Errors
• Roles and permissions
• Security at EvoHub