wyre-ai/msp-claude-plugins/api-patterns

KPN API Patterns

Overview

KPN exposes its APIs through an Apigee gateway at api-prd.kpn.com. The kpn-mcp sidecar mints and caches OAuth2 client-credentials tokens itself; Conduit only forwards the stored keys as headers. Start any troubleshooting with kpn_test_connection.

Credentials and token realms

The two realms mint tokens from different endpoints. MSM access is tied to a KPN business-mobile customer and may need an app that KPN set up for that customer, which is why it has its own optional pair.

Key concepts

• A valid key is not an entitled key. KPN mints a token for any valid

project, even if the product was never added to it. The call then fails with 401 or 403. Tell the user to add the product to their project on developer.kpn.com rather than to re-enter credentials.

• Quotas are per project and unpublished. Responses carry quota-*

headers; kpn_test_connection reports the last seen values. On 429 the error includes when the quota resets.

• Test and production share one host. The account tier (demo/prod)

is a property of the project, reported by kpn_test_connection.

Writes

The five MSM write tools and kpn_mobile_contracts_get_puk ask the user to confirm before running. Clients that cannot show a prompt must pass confirm_destructive_action: true, and should only do so after the user has agreed in the conversation.

MSM writes create orders. Success means KPN accepted the order, not that the SIM is already blocked or replaced; the order may sit in UNAUTHORIZED until someone approves it (kpn_mobile_orders_authorize).

A failed write is never retried automatically, because a duplicate block or authorize is a real side effect. Before retrying after an error, check kpn_mobile_orders_list for an order that already went through.

Common errors