Consumers API

Consumers are invited by email. The consumer id in the path is the consumer record sKey. cognitoSub is the MCP consumer-pool subject. An entitlement body is mcpId or proxyId. Send one of them.

Endpoints

Method	Path	What it does
GET	`/api/clients/:clientId/consumers`	List consumers
POST	`/api/clients/:clientId/consumers`	Invite a consumer
GET	`/api/clients/:clientId/consumers/:consumerId`	Read a consumer
DELETE	`/api/clients/:clientId/consumers/:consumerId`	Delete a consumer
GET	`/api/clients/:clientId/consumers/:consumerId/entitlements`	List entitlements for a consumer
POST	`/api/clients/:clientId/consumers/:consumerId/entitlements`	Create an entitlement
DELETE	`/api/clients/:clientId/consumers/:consumerId/entitlements/:resourceId`	Delete an entitlement
GET	`/api/clients/:clientId/proxies/:proxyId/entitlements`	List entitlements on a proxy
GET	`/api/clients/:clientId/mcps/:mcpId/entitlements`	List entitlements on an MCP server

Invite a consumer

POST /api/clients/:clientId/consumers creates the consumer and sends an invite. A second invite for the same email returns 409 when that consumer already has an identity.

Request body

Parameter	Type	Required	Description
`email`	string	✓	Address the invite is sent to. Stored in lowercase.
`givenName`	string	✓	Given name, 3–128 characters.
`familyName`	string	✓	Family name, 3–128 characters.

Returns a consumers array. message is "Consumer invited" for a new identity, or "Consumer linked to an existing identity" when the email already exists in the consumer pool. The attributes match List consumers.

List consumers

GET /api/clients/:clientId/consumers returns every consumer for the organisation in one response. GET /api/clients/:clientId/consumers/:consumerId returns one consumer.

Response attributes

Attribute	Type	Description
`consumers`	array	One or more consumer objects.
`consumers[].sKey`	string	Consumer id. Pass this as `consumerId`.
`consumers[].pKey`	string	Organisation id.
`consumers[].cognitoSub`	string	MCP consumer-pool subject.
`consumers[].email`	string	Invited email address.
`consumers[].givenName`	string	Given name.
`consumers[].familyName`	string	Family name.
`consumers[].status`	string	`"active"` or `"inactive"`.
`consumers[].createdIdentity`	boolean	`true` when the invite created the pool user.
`consumers[].invitedBy`	string	User id of the caller who sent the invite.
`consumers[].createdAt`	string	ISO 8601 creation time.
`consumers[].updatedAt`	string	ISO 8601 last update time.
`message`	string	`"Success"`.

Create an entitlement

POST /api/clients/:clientId/consumers/:consumerId/entitlements grants the consumer one MCP server or one proxy.

Request

curl -X POST "https://api.requestrocket.com/api/clients/:clientId/consumers/:consumerId/entitlements" \
  -H "Authorization: u-your-token" \
  -H "Content-Type: application/json" \
  -d '{
  "mcpId": "c5a9e013-8d27-4b61-a4f0-1e6c3b8d5a47"
}'

import axios from "axios";

const response = await axios.request({
  method: "POST",
  url: "https://api.requestrocket.com/api/clients/:clientId/consumers/:consumerId/entitlements",
  headers: {
    "Authorization": "u-your-token",
    "Content-Type": "application/json",
  },
  data: {
  "mcpId": "c5a9e013-8d27-4b61-a4f0-1e6c3b8d5a47"
}
});

console.log(response.status, response.data);

import requests

response = requests.request(
    "POST",
    "https://api.requestrocket.com/api/clients/:clientId/consumers/:consumerId/entitlements",
    headers={
        "Authorization": "u-your-token",
        "Content-Type": "application/json",
    },
    data="{\n  \"mcpId\": \"c5a9e013-8d27-4b61-a4f0-1e6c3b8d5a47\"\n}"
)
print(response.status_code, response.json())

package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    payload := strings.NewReader(`{
  "mcpId": "c5a9e013-8d27-4b61-a4f0-1e6c3b8d5a47"
}`)
    req, _ := http.NewRequest("POST", "https://api.requestrocket.com/api/clients/:clientId/consumers/:consumerId/entitlements", payload)
    req.Header.Set("Authorization", "u-your-token")
    req.Header.Set("Content-Type", "application/json")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(resp.StatusCode, string(body))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.requestrocket.com/api/clients/:clientId/consumers/:consumerId/entitlements"))
            .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"mcpId\": \"c5a9e013-8d27-4b61-a4f0-1e6c3b8d5a47\"\n}"))
            .header("Authorization", "u-your-token")
            .header("Content-Type", "application/json")
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}

Responses

{
  "entitlements": [
    {
      "consumerId": "e2b6d094-1f73-4a58-8c0e-9d3a5f7b2c16",
      "clientId": "b3a1c7d2-5e44-4f0a-9c1e-7d2f8a6b1c90",
      "mcpId": "c5a9e013-8d27-4b61-a4f0-1e6c3b8d5a47",
      "cognitoSub": "e2b6d094-1f73-4a58-8c0e-9d3a5f7b2c16",
      "mcpRegion": "us-east-2",
      "resourceType": "mcp",
      "status": "active",
      "expiresAt": null,
      "createdAt": "2026-11-02T07:30:00.000Z",
      "updatedAt": "2026-11-02T07:30:00.000Z"
    }
  ],
  "message": "Entitlement created"
}

{
  "message": "Provide either mcpId or proxyId"
}

{
  "message": "Unauthorized"
}

{
  "Message": "User is not authorized to access this resource with an explicit deny in an identity-based policy"
}

{
  "message": "method / endpoint not supported"
}

Returns an entitlements array with message set to "Entitlement created".

Request body

Send mcpId or proxyId. Sending both, or neither, returns 400. On this path consumerId is taken from the URL.

Parameter	Type	Required	Description
`mcpId`	string	one of	MCP server to grant. Omit when granting a proxy.
`proxyId`	string	one of	Proxy to grant. Omit when granting an MCP server.
`expiresAt`	string	—	ISO-8601 timestamp in the future. Omit for a grant that does not expire.
`consumerId`	string	—	The URL supplies the consumer on this path.

Response attributes

Attribute	Type	Description
`entitlements`	array	One or more entitlement objects.
`entitlements[].sKey`	string	Granted resource id. Pass this as `resourceId` to delete the entitlement.
`entitlements[].pKey`	string	Consumer id.
`entitlements[].consumerId`	string	Consumer id.
`entitlements[].clientId`	string	Organisation id.
`entitlements[].cognitoSub`	string	Consumer-pool subject copied onto the grant.
`entitlements[].resourceType`	string	`"mcp"` or `"proxy"`.
`entitlements[].mcpId`	string or null	MCP server id, when the grant is for an MCP server.
`entitlements[].proxyId`	string or null	Proxy id, when the grant is for a proxy.
`entitlements[].mcpRegion` or `proxyRegion`	string	Region of the granted resource.
`entitlements[].status`	string	`"active"`.
`entitlements[].expiresAt`	string or null	ISO 8601 expiry, or `null` when the grant does not expire.
`entitlements[].createdAt`	string	ISO 8601 creation time.
`entitlements[].updatedAt`	string	ISO 8601 last update time.
`message`	string	`"Entitlement created"`.

List entitlements

These reads return an entitlements array with message set to "Success". Each item matches the attributes above.

Method	Path
GET	`/api/clients/:clientId/consumers/:consumerId/entitlements`
GET	`/api/clients/:clientId/proxies/:proxyId/entitlements`
GET	`/api/clients/:clientId/mcps/:mcpId/entitlements`

Delete an entitlement

DELETE /api/clients/:clientId/consumers/:consumerId/entitlements/:resourceId removes the grant. resourceId is the MCP server id or the proxy id.

Request

curl -X DELETE "https://api.requestrocket.com/api/clients/:clientId/consumers/:consumerId/entitlements/:resourceId" \
  -H "Authorization: u-your-token"

import axios from "axios";

const response = await axios.request({
  method: "DELETE",
  url: "https://api.requestrocket.com/api/clients/:clientId/consumers/:consumerId/entitlements/:resourceId",
  headers: {
    "Authorization": "u-your-token",
  }
});

console.log(response.status, response.data);

import requests

response = requests.request(
    "DELETE",
    "https://api.requestrocket.com/api/clients/:clientId/consumers/:consumerId/entitlements/:resourceId",
    headers={
        "Authorization": "u-your-token",
    }
)
print(response.status_code, response.json())

package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    var payload io.Reader
    req, _ := http.NewRequest("DELETE", "https://api.requestrocket.com/api/clients/:clientId/consumers/:consumerId/entitlements/:resourceId", payload)
    req.Header.Set("Authorization", "u-your-token")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(resp.StatusCode, string(body))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.requestrocket.com/api/clients/:clientId/consumers/:consumerId/entitlements/:resourceId"))
            .method("DELETE", HttpRequest.BodyPublishers.noBody())
            .header("Authorization", "u-your-token")
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}

Responses

{
  "message": "Entitlement deleted"
}

{
  "message": "Valid entitlement is required"
}

{
  "message": "Unauthorized"
}

{
  "Message": "User is not authorized to access this resource with an explicit deny in an identity-based policy"
}

{
  "message": "method / endpoint not supported"
}

Returns message set to "Entitlement deleted".

App guide

Do this in the app

MCP servers

Publish an MCP server over a proxy or direct

Inbound credentials

What the caller presents

Endpoints

Invite a consumer

Request body

List consumers

Response attributes

Create an entitlement

Request

Responses

Request body

Response attributes

List entitlements

Delete an entitlement

Request

Responses

Next

App guide

MCP servers

Inbound credentials

On this page