/entitlements/catalog - Create an add-on type | my.nethesis.it API documentation

/entitlements/catalog - Create an add-on type

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL


        
          
            https://api.my.nethesis.it/mcp

Standard setup for AI tools providing an mcp.json file

{
  "my.nethesis.it MCP server": {
    "url": "https://api.my.nethesis.it/mcp"
  }
}

POST /entitlements/catalog

Bearer auth

Add a new add-on type to the catalog. Only the owner organization or a Super Admin can manage the catalog (403 otherwise).

application/json

Body Required

id string Required

Catalog id: lowercase kebab-case, convention nsec-, ns8- or -
display_name string Required

Human-readable name
description string

Optional longer description
scoped boolean

True when grants can be narrowed to a single application instance (per-application-instance modules)

Default value is false.
kind string

Add-on kind

Values are service or module. Default value is service.
system_type string

Restricts the add-on to one system type. Empty/omitted = any type.

Values are nsec or ns8.
legacy_alias string

Old wire id (lowercase kebab-case) consumers still call on GET /auth/service/{id}
applies_to string

Application (applications.instance_of) the module applies to. Required in practice for kind=module: omitted, it falls back to the id prefix, which is wrong for hyphenated app names. Ignored for services.
purchasable boolean

Whether the add-on is on sale. Defaults to true when omitted.

Default value is true.

Responses

201 application/json

Catalog item created successfully
Hide response attributes Show response attributes object
- code integer
- message string
- data object
  
  One grantable add-on type. Ids are lowercase kebab-case; convention: nsec-<service> (firewall services), ns8-<app> (application enablement on a cluster) or <app>-<module> (per-application-instance modules, scoped: true; applies_to names the application, since the id prefix is ambiguous for hyphenated app names). legacy_alias is the old wire id the appliance feeds still call on GET /auth/service/{id} — legacy ids are never renamed.
  
  Hide data attributes Show data attributes object
  
  id string
  
  Catalog id (lowercase kebab-case, immutable)
  
  display_name string
  
  Human-readable name
  
  description string
  
  Optional longer description
  
  scoped boolean
  
  True when grants can be narrowed to a single application instance via scope (per-application-instance modules). Immutable.
  
  kind string
  
  Both kinds are sellable on the shop — services are firewall add-ons granted system-wide, modules are add-ons for a single application instance of an NS8 cluster
  
  Values are service or module.
  
  system_type string
  
  Restricts the add-on to one system type. Empty/omitted = any type.
  
  Values are nsec or ns8.
  
  legacy_alias string
  
  Old wire id consumers still call on GET /auth/service/{id} (only for types migrated from the legacy my)
  
  applies_to string
  
  Application (applications.instance_of) a module add-on applies to. Empty for system-wide services. Stored explicitly because the - id prefix is ambiguous when the app name itself contains a hyphen (nethvoice-proxy).
  
  purchasable boolean
  
  False when the add-on exists but is not on sale: the shop product is unpublished, or it is sold off-line only. The add-on stays visible wherever it is granted — only the buy action is withheld. Separate from the per-organization allowlist, which answers who may buy rather than whether it is on sale at all.
  
  in_use boolean
  
  True when at least one grant references the item — revoked and expired grants included, since they are kept for audit and block the delete all the same. Clients should disable the delete action for these items: DELETE /entitlements/catalog/{id} answers 409.
  
  created_at string(date-time)
  
  updated_at string(date-time)
400 application/json

Invalid id or legacy_alias (lowercase kebab-case required), invalid kind (service/module) or system_type (nsec/ns8/empty)
Hide response attributes Show response attributes object
- code integer
  
  HTTP error code
- message string
  
  Error message
- data object
  
  Hide data attributes Show data attributes object
  
  type string
  
  Type of error
  
  Values are validation_error or external_api_error.
  
  errors array[object]
  
  Hide errors attributes Show errors attributes object
  
  key string
  
  Field name that failed validation
  
  message string
  
  Error code or message
  
  value string
  
  Value that failed validation
  
  details
  
  Additional error details
401 application/json

Unauthorized - invalid or missing token
Hide response attributes Show response attributes object
- code integer
- message string
- data object | null
403 application/json

Forbidden - insufficient permissions
Hide response attributes Show response attributes object
- code integer
- message string
- data object | null
409 application/json

Catalog item already exists
Hide response attributes Show response attributes object
- code integer
- message string
- data object | null
500 application/json

Internal server error
Hide response attributes Show response attributes object
- code integer
- message string
- data object | null

POST /entitlements/catalog

curl \
 --request POST 'https://api.your-domain.com/api/entitlements/catalog' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"id":"nsec-blacklist","display_name":"Blacklist","description":"IP and DNS blacklist feed for NethSecurity","scoped":false,"kind":"service","system_type":"nsec","legacy_alias":"ng-blacklist","applies_to":"nethvoice","purchasable":true}'

Request examples

{
  "id": "nsec-blacklist",
  "display_name": "Blacklist",
  "description": "IP and DNS blacklist feed for NethSecurity",
  "scoped": false,
  "kind": "service",
  "system_type": "nsec",
  "legacy_alias": "ng-blacklist",
  "applies_to": "nethvoice",
  "purchasable": true
}

Response examples (201)

{
  "code": 201,
  "message": "catalog item created successfully",
  "data": {
    "id": "nsec-blacklist",
    "display_name": "Blacklist",
    "description": "IP and DNS blacklist feed for NethSecurity",
    "scoped": false,
    "kind": "service",
    "system_type": "nsec",
    "legacy_alias": "ng-blacklist",
    "applies_to": "nethvoice",
    "purchasable": true,
    "in_use": true,
    "created_at": "2026-07-01T10:00:00Z",
    "updated_at": "2026-07-01T10:00:00Z"
  }
}

Response examples (400)

{
  "code": 400,
  "message": "validation failed",
  "data": {
    "type": "validation_error",
    "errors": [
      {
        "key": "username",
        "message": "required",
        "value": "string"
      }
    ]
  }
}

Response examples (401)

{
  "code": 401,
  "message": "invalid token",
  "data": {}
}

Response examples (403)

{
  "code": 403,
  "message": "insufficient permissions",
  "data": {}
}

Response examples (409)

{
  "code": 409,
  "message": "catalog item already exists",
  "data": {}
}

Response examples (500)

{
  "code": 500,
  "message": "internal server error",
  "data": {}
}