CognethicsCognethicsDevelopers

Get a developer workspace

Your Cognethics workspace is a development tenant — your own API endpoint, API keys, and an MCP server wired to the full platform. Workspaces are provisioned and configured for your team: credentials and tenant data on a governed platform are set up for an identified principal, not anonymously minted. From there, you mint and rotate your own keys.

Step 1: Get a workspace

Go to developers.cognethics.com/signup/, tell us who you are and what you're building, and we provision a workspace for you — your own tenant subdomain (like alice.cognethics.com), bound to your identity.

It's a fast front door: the form routes straight to the team that sets it up.

If you've used Cognethics before, sign in instead — you already have access.

Step 2: Mint your API key

Once your workspace is live, sign in to the developer dashboard and mint a scoped API key (ck_…). The plaintext is shown exactly once — save it.

Write down your API key now. You'll use it for every API call. Rotate it or mint more from the dashboard anytime.

ck_a1b2c3d4abcdefghijklmnopqrstuvwxyz...

Step 3: Make your first API call (1 minute)

Verify the key works. Grab your subdomain from the welcome email (for example, alice) and run this in your terminal:

curl -H "Authorization: Bearer ck_YOUR_KEY" \
  https://alice.cognethics.com/api/v1/dev/me/

Replace ck_YOUR_KEY with your actual key and alice with your subdomain.

Expected response:

{
  "authenticated": true,
  "key": {
    "prefix": "ck_a1b2c3d4",
    "name": "Sandbox key",
    "created_at": "2026-05-06T17:00:00+00:00",
    "scopes": []
  },
  "user": { "id": "...", "email": "[email protected]" },
  "tenant": { "id": "...", "subdomain": "alice" }
}

A 200 means you're in. A 401 usually means the key or subdomain is misspelled.

Sibling endpoints under the same namespace:

  • GET /api/v1/dev/ping/ — no auth, smoke-tests the namespace itself
  • GET /api/v1/dev/echo/ — echoes back your query params and tenant subdomain; useful for debugging proxies

Call the platform over REST

The same ck_ key drives three REST endpoints that wrap the platform's tool dispatch — identical RBAC, budget, and audit enforcement as the MCP SSE endpoint, just returned as plain JSON. They let you discover and run tools without an MCP client.

List the tools your key can dispatch:

curl -H "Authorization: Bearer ck_YOUR_KEY" \
  https://alice.cognethics.com/api/v1/dev/tools

Walk the typed Prism handler catalog by dimension (mega_tools, apps, entities, operations, schema, stats):

curl -H "Authorization: Bearer ck_YOUR_KEY" \
  "https://alice.cognethics.com/api/v1/dev/introspect?dimension=mega_tools"

Execute a single tool by name. Pass the tool's arguments under arguments:

curl -X POST -H "Authorization: Bearer ck_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"prism_whoami","arguments":{}}' \
  https://alice.cognethics.com/api/v1/dev/call

/call returns whatever the tool returns. A 404 means the tool name is unknown; a 400 means the arguments didn't validate.

Step 4: Connect Claude (1 minute, optional)

Your sandbox speaks the standard Model Context Protocol over HTTP+SSE with OAuth 2.1 + PKCE. Most MCP-aware clients negotiate the OAuth flow automatically — pick yours below.

Claude Desktop

  1. Open Claude Desktop → Settings → Developer → Edit Config.

  2. Add Cognethics to the mcpServers block:

    {
  "mcpServers": {
    "cognethics": {
      "url": "https://alice.cognethics.com/api/mcp/sse"
    }
  }
}

    Replace alice with your subdomain.

  3. Restart Claude Desktop. The first connection triggers an OAuth approval dialog in your browser — pick a scope (mcp:read, mcp:write, or mcp:execute) and approve.

Claude Code (CLI)

  1. Edit ~/.claude/settings.json and add:

    {
  "mcpServers": {
    "cognethics": {
      "url": "https://alice.cognethics.com/api/mcp/sse",
      "type": "http"
    }
  }
}

  2. Restart your Claude Code session.

  3. Type /mcp — Cognethics will appear in the connected-servers list.

claude.ai (web)

  1. Open claude.ai → Settings → Connectors → Add custom MCP.
  2. Paste https://alice.cognethics.com/api/mcp/sse.
  3. Browser-based Dynamic Client Registration handles the OAuth flow. Approve the scope set you want and you're connected.

What can you do now?

Your sandbox connects you to the full platform. Try these prompts in Claude:

  • "List the 5 most recent invoices in my organization."
  • "Search for documents about valve maintenance."
  • "Create a new work order with these details: ..."
  • "Show me the open tickets assigned to me."

The exact tools available depend on what your tenant is provisioned for. Browse the full catalog at /reference/handlers/.

Spend and quotas

Your sandbox has a daily spend cap of $0.50 USD by default. When you hit the daily limit, the sandbox auto-pauses until the next UTC day. This protects against runaway costs.

For higher limits or production work, upgrade to a paid account.

Next steps

  • Explore the handler catalog — /reference/handlers/ lets you browse every tool the platform exposes, searchable by app or tool name.
  • Read the MCP details — /quickstart/mcp/ goes deeper into sandbox keys, OAuth, and API responses.
  • Write a custom tool — /recipes/custom-tool/ shows how to extend the platform with your own MCP handler.
  • Wire up webhooks — /webhooks/ covers HMAC-signed event delivery and retries.

Questions? Reach our support team through the contact form.