Build on Hekk

Register your agent, send your user through the Hekk consent screen, then call 12 tools over MCP or REST — the same registry powers both.

Agents are public OAuth clients: authorization-code + PKCE (S256). There is no client secret — the client_id is not a credential.

Quickstart

1. 1. Register your agent below — you get a client_id instantly.

2. 2. Send your user to the authorize URL (they log in and set scopes + caps):

   https://hekkapp.com/en/agents/connect?response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri>&scope=discover%20book&state=<state>&code_challenge=<S256_challenge>&code_challenge_method=S256

3. 3. Exchange the code for tokens (access 1h, refresh 30d rotating):

   curl -X POST https://hekkapp.com/api/agent/v1/oauth/token \
     -H "Content-Type: application/json" \
     -d '{
       "grant_type": "authorization_code",
       "code": "<code>",
       "redirect_uri": "<redirect_uri>",
       "client_id": "<client_id>",
       "code_verifier": "<pkce_verifier>"
     }'

   curl -X POST https://hekkapp.com/api/agent/v1/oauth/token \
     -H "Content-Type: application/json" \
     -d '{
       "grant_type": "refresh_token",
       "refresh_token": "<refresh_token>",
       "client_id": "<client_id>"
     }'

4. 4. Call tools over MCP or REST — spending tools need an Idempotency-Key over REST:

   {
     "mcpServers": {
       "hekk": { "url": "https://hekkapp.com/agents/mcp" }
     }
   }

   curl -X POST https://hekkapp.com/api/agent/v1/tools/create_booking \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: <unique-key>" \
     -d '{
       "providerId": "<providerId>",
       "serviceId": "<serviceId>",
       "address": "Building 12, Road 3419, Manama",
       "acceptedPrice": 25.000
     }'

Access tokens live 1 hour, but the grant, agent and customer are re-validated on EVERY call — revocation and suspension bite immediately, not at expiry.

Quickstart & endpoints

Scopes

Tool reference

{ "categories": [{ "slug": "plumbing", "nameEn": "Plumbing", "nameAr": "السباكة" }] }

{ "quotes": [{ "providerId": "…", "providerName": "…", "startingPrice": 15.000, "currency": "BHD" }] }

{ "bookingId": "…", "status": "PENDING", "price": 25.000 }

{ "status": "ACCEPTED", "price": 25.000, "provider": { "name": "…", "phone": "+973…" } }

{ "bookings": [{ "bookingId": "…", "status": "COMPLETED", "hasReview": false }] }

{ "messageId": "…", "at": "2026-01-01T10:00:00.000Z" }

{ "messages": [{ "from": "PROVIDER", "body": "On my way", "viaAgent": false }] }

{ "bookingId": "…", "status": "COMPLETED" }

{ "paymentId": "…", "status": "AUTHORIZED", "method": "CASH" }

{ "reviewId": "…", "attribution": "via_agent" }

{ "bookingId": "…", "status": "CANCELLED" }

{ "actions": [{ "tool": "create_booking", "result": "ok", "amount": 25.000 }] }

{ "approvalId": "…", "status": "APPROVED", "tool": "create_booking", "bookingId": "…", "expiresAt": "…" }

Guardrails, errors & limits

{
  "status": "pending_human_approval",
  "approval": {
    "id": "<approvalId>",
    "confirmUrl": "https://hekkapp.com/en/agents/approvals/<token>",
    "expiresAt": "2026-01-01T12:30:00.000Z"
  },
  "reason": "This action is over your spend limit and needs your confirmation."
}

// Then poll the outcome (do NOT retry the original call with a new Idempotency-Key):
// POST https://hekkapp.com/api/agent/v1/tools/get_approval  { "approvalId": "<approvalId>" }
// → { "status": "PENDING" | "APPROVED" | "DECLINED" | "EXPIRED", "bookingId": "…" }

Change (Jul 2026): when an agent requests full access (no scope parameter), the consent screen now renders spending scopes (book, complete, pay, review) UNCHECKED by default — users must opt in explicitly. Narrow your scope request to exactly what your agent needs.