Getting Started with the API

Base URL

All API requests are made to the following base URL:

https://api.kpnthings.com

The API currently has a single version. All changes are backward-compatible.

Requests use standard HTTP methods (GET, POST, PUT, DELETE), and both requests and responses are in JSON format.

Authentication

Access to the KPN Things API is secured through GRIP, KPN’s identity and access management platform. API keys and tokens are managed in GRIP, independently of individual user accounts.

Every request to the KPN Things API must be authenticated with a bearer token (an access token) obtained from GRIP using an API key.

API Keys in GRIP

• An API Key is a standalone entity within a GRIP tenant (your customer environment).

• API Keys are not user-bound; they are service credentials that can be used by applications or systems.

• Best practice: create separate API keys for each system or integration that needs access.

Access Tokens

To call the KPN Things API, you must exchange your API Key for a short-lived access token:

• Tokens are valid for 1 hour.

• Include the token in every API request via the Authorization header:

Authorization: Bearer <accessToken>

• There are no refresh tokens. When a token expires, simply request a new one from GRIP.

More background on the authentication model used is available in the GRIP Knowledge Base under Machine Authentication:

• Machine Authentication Introduction

• Machine Authentication OAuth

Required Values

When requesting an access token from GRIP, you will need the following:

Step 1: Find your GRIP Tenant ID

1. Log in to MijnKPN Zakelijk.

2. Hover over your name in the top right corner.

3. In the overflow menu your GRIP Tenant ID is displayed right above your name.

Step 2: Create an API Key in GRIP

To create an API key, you need administrator access to the GRIP portal.

• If you have a KPN Developer account, you are automatically an administrator.

• If you have a MijnKPN Zakelijk account, you may need to request access from your local administrator.

2.1 Open API Key Management

• Log in to the GRIP Portal.

• Open the Admin panel from the role dropdown.

• In the left-hand menu, go to Identity → API Keys.

• Click Add to create a new API Key.

2.2. Create new API Key

• Enter a Display name and Description for your API Key.

• Click Add to create it.

2.3. Grant access to KPN Things

• On the API Key details page, open the Services and Roles tab.

• Click Add a service.

• Select KPN Things Portal from the list and click Add.

• Assign the desired role and access level to the API Key.

• Click Save to apply.

2.4 Retrieve the Credentials

• Go back to the General Information tab of your new API Key.

• Copy the ID (Client ID) and Secret (Client Secret).

• Store them securely — you will use them to request access tokens.

Step 3: Request an Access Token

With your Tenant ID, Application ID, Client ID, and Client Secret, you can now request an access token from GRIP.

POST https://auth.grip-on-it.com/v2/{tenantId}/oidc/idp/c1/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "audience": "4dc82561-f65f-523g-dek9-6c79ec314f02",
  "client_id": "<your-api-key-id>",
  "client_secret": "<your-api-key-secret>"
}

Example Response:

{
  "accessToken": "<your-access-token>",
  "token_type": "Bearer",
  "expiresIn": 3600
}

Use this token in the Authorization header for all subsequent API requests.

API access to customer environments as a reseller

Pagination

The API uses cursor-based pagination. This approach ensures consistent performance when navigating large datasets.

When requesting a list of resources, the response may contain next and prev links. These links contain an opaque cursor that identifies the next or previous page.

{
  "items": [ ... ],
  "next": "https://api.kpnthings.com/devices?cursor=abc123",
  "prev": "https://api.kpnthings.com/devices?cursor=xyz789"
}

• Use the next link to load the following page.

• Use the prev link to load the previous page.

• The API does not provide the total number of results or pages.

You can control the maximum number of results per page using the limit query parameter:

GET /downlinks?limit=50

Filtering

You can filter results by adding query parameters. The most common filters are:

Example:

GET /downlinks?modifiedSince=2025-09-01T00:00:00Z

Sorting

Use the sort parameter to order results. Multiple attributes can be combined in a comma-separated list. Prefix an attribute with - to sort in descending order.

Examples:

• sort=createdAt,id → sort by createdAt ascending, then id ascending

• sort=-createdAt,id → sort by createdAt descending, then id ascending

Example Request:

GET /downlinks?modifiedSince=2025-09-01T00:00:00Z&limit=100&sort=-modifiedAt

Error Handling

The KPN Things API uses the Problem Details for HTTP APIs format (application/problem+json) to return error information. This provides a consistent structure for all error responses.

Response Format

An error response includes standard fields defined by RFC 7807, as well as optional details when available.

Example Error Response:

{
  "title": "Invalid request",
  "status": 400,
  "detail": "The field 'limit' must be greater than zero.",
  "instance": "/downlinks?limit=-1"
}

Standard Fields

Common Error Codes

• 400 Bad Request — The request is invalid (e.g., malformed parameters, invalid values).

• 401 Unauthorized — The request is missing a valid access token.

• 403 Forbidden — The token is valid, but you do not have permission to perform this action.

• 404 Not Found — The requested resource does not exist.

• 409 Conflict — A conflicting operation is already in progress, or resource constraints prevent the request.

• 429 Too Many Requests — You have hit a rate limit.

• 500 Internal Server Error — An unexpected error occurred.

Handling Errors in Clients

When consuming the API, clients should:

1. Check the HTTP status code to determine the general error category.

2. Inspect the title field for programmatic handling of known error types.

3. Display or log the detail field to help users or developers troubleshoot.