EvoHub Docs Sign in

Organization API › Roles

Create 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

POST/api/v1/roles

Creates a custom role. Every permission must be in the catalog and held by the key.

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

Authorization

Any one of:

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

201

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 (INVALID_BODY), no name or one over 100 characters (VALIDATION_ERROR), or a permission not in the catalog (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.

409

A role with that name exists (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 POST 'https://evohub.io/api/v1/roles' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  -d '{
  "name": "Incident responder",
  "description": "Answers alerts and runs incidents",
  "permissions": [
    "oncall:alert:read",
    "oncall:alert:respond",
    "oncall:incident:write"
  ]
}'

Last updated