EvoHub Docs Sign in

Organization API › Roles

Update a role

Use with AI
View as MarkdownThis page as plain text, for pasting into an AI tool Open in ClaudeAsk Claude questions about this page Open in ChatGPTAsk ChatGPT questions about this page
Connect to Cursor / VS Code / ClaudeSearch and read these docs from your AI tool (MCP server)

MCP server URL

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

Add to CursorAdd to VS Code

Claude Code

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

Claude (claude.ai and Claude Desktop): Settings → Connectors → Add custom connector, and paste the URL above.

Claude Desktop — claude_desktop_config.json

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

Cursor — ~/.cursor/mcp.json

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

VS Code — .vscode/mcp.json

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

llms.txtllms-full.txt

PATCH/api/v1/roles/{id}

Replaces the role's name, description and permissions: send all three (name is required; a permissions left out keeps the list). Every holder's access changes at once. Permissions added must be held by the key; a default role is edited only by an administrator (ADMIN_ONLY).

Permission (API-key scope): identity:role:write.

Authorization

Any one of:

Parameters

Path parameters

  • id string required
    The id of the member (usr_…), team (team_…), role (role_…), invitation (inv_…) or organization (org_…) the path names.

Request body required

Content type: application/json

Type: RoleWrite

  • name string required
    Min length: 1 · Max length: 100
  • description string
  • permissions array of string
    Each must be in the catalog (else 400 UNKNOWN_PERMISSION) and held by the key (else 403).

Responses

200

The role.

Content type: application/json

Type: object

  • data Role required
    Show Role properties
    • id string required
    • org_id string required
    • name string required
    • description string
    • permissions array of string required
      Permission names from the catalog (GET /api/v1/permissions).
    • built_in string
      Set on the three default roles, which cannot be deleted and only an administrator edits.
      One of: admin member viewer
    • created_at string (date-time) required
    • updated_at string (date-time) required
  • success boolean required
    Value: true

400

Not JSON, no name, or an unknown permission (INVALID_BODY, VALIDATION_ERROR, UNKNOWN_PERMISSION).

Content type: application/json

Type: Error

  • error object required
    • code string required
      Machine-readable code. Branch on this.
    • message string required
      Human-readable explanation.
    • request_id string
      The response's X-Request-ID; quote it to support.

401

No API key was sent, or it is unknown, revoked or expired (UNAUTHORIZED).

Content type: application/json

Type: Error

  • error object required
    • code string required
      Machine-readable code. Branch on this.
    • message string required
      Human-readable explanation.
    • request_id string
      The response's X-Request-ID; quote it to support.

403

The key lacks the scope (FORBIDDEN); the change would grant a permission the key does not hold (FORBIDDEN, naming it); or only an administrator may do it (ADMIN_ONLY).

Content type: application/json

Type: Error

  • error object required
    • code string required
      Machine-readable code. Branch on this.
    • message string required
      Human-readable explanation.
    • request_id string
      The response's X-Request-ID; quote it to support.

404

No such role in the organization (NOT_FOUND).

Content type: application/json

Type: Error

  • error object required
    • code string required
      Machine-readable code. Branch on this.
    • message string required
      Human-readable explanation.
    • request_id string
      The response's X-Request-ID; quote it to support.

409

Another role has that name (ROLE_NAME_TAKEN).

Content type: application/json

Type: Error

  • error object required
    • code string required
      Machine-readable code. Branch on this.
    • message string required
      Human-readable explanation.
    • request_id string
      The response's X-Request-ID; quote it to support.

429

Too many requests (RATE_LIMITED). Wait Retry-After seconds.

Headers

  • Retry-After integer
    Seconds to wait.

Content type: application/json

Type: Error

  • error object required
    • code string required
      Machine-readable code. Branch on this.
    • message string required
      Human-readable explanation.
    • request_id string
      The response's X-Request-ID; quote it to support.

500

Something went wrong on EvoHub's side (INTERNAL_ERROR). Retry later.

Content type: application/json

Type: Error

  • error object required
    • code string required
      Machine-readable code. Branch on this.
    • message string required
      Human-readable explanation.
    • request_id string
      The response's X-Request-ID; quote it to support.

Example request

curl -X PATCH 'https://evohub.io/api/v1/roles/string' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  -d '{
  "name": "Incident responder",
  "description": "Answers alerts, runs incidents and writes postmortems",
  "permissions": [
    "oncall:alert:read",
    "oncall:alert:respond",
    "oncall:incident:write",
    "oncall:postmortem:write"
  ]
}'

Last updated