Overview

This guide walks you through using N-central's Device Filtering and Registration APIs. These APIs allow you to retrieve filter information and manage registration tokens for secure agent deployment. In this guide, you'll learn how to:

1. List and retrieve device filters
2. Get registration tokens at different organizational levels
3. Handle API responses and errors
4. Follow best practices for implementation

Device Filters API

List Device Filters

Retrieve a list of all device filters available to your organization. This endpoint supports pagination and sorting to help you manage large filter lists effectively.

Required Headers:

• Authorization: Bearer <YOUR_API_ACCESS_TOKEN>
• Content-Type: application/json

Optional Query Parameters:

• viewScope: Controls which filters to return (ALL or OWN_AND_USED)
• pageNumber: Page number starting from 1
• pageSize: Number of items per page (1-1000)
• sortBy: Field to sort by
• sortOrder: Sort direction (asc, ascending, natural, desc, descending, reverse)

Request

GET /api/device-filters
Authorization: Bearer <YOUR_API_ACCESS_TOKEN>

Response

Upon success, N-central returns a 200 status code along with the list of filters:

{
    "data": [
        {
            "filterId": "75",
            "filterName": "Laptops - Windows",
            "description": "Laptop devices running Windows"
        }
    ],
    "totalItems": 1
}

Key points to note in the response:

• filterId: Unique identifier for referencing the filter
• filterName: Human-readable filter name
• description: Detailed description of the filter's purpose
• totalItems: Total number of filters available

Registration Token APIs

The Registration Token APIs provide secure access to registration tokens at different organizational levels. These tokens are essential for secure agent deployment.

Get Customer Registration Token

Retrieve a registration token for a specific customer.

Required Path Parameter:

• customerId: The unique identifier of the customer

Request

GET /api/customers/{customerId}/registration-token
Authorization: Bearer <YOUR_API_ACCESS_TOKEN>

Response

Success response (200):

{
    "data": {
        "registrationToken": "2f64ee5e-7c37-dce7-ffd2-d32912609623",
        "registrationTokenExpiryDate": "2024-05-01T23:59:00-04:00[America/New_York]"
    }
}

Get Site Registration Token

Retrieve a registration token for a specific site.

Required Path Parameter:

• siteId: The unique identifier of the site

Request

GET /api/sites/{siteId}/registration-token
Authorization: Bearer <YOUR_API_ACCESS_TOKEN>

Response

Success response (200):

{
    "data": {
        "registrationToken": "2f64ee5e-7c37-dce7-ffd2-d32912609623",
        "registrationTokenExpiryDate": "2024-05-01T23:59:00-04:00[America/New_York]"
    }
}

Get Organization Unit Registration Token

Retrieve a registration token for an organization unit. Note: This endpoint only supports CUSTOMER and SITE level organization units.

Required Path Parameter:

• orgUnitId: The unique identifier of the organization unit

Request

GET /api/org-units/{orgUnitId}/registration-token
Authorization: Bearer <YOUR_API_ACCESS_TOKEN>

Response

Success response (200):

{
    "data": {
        "registrationToken": "2f64ee5e-7c37-dce7-ffd2-d32912609623",
        "registrationTokenExpiryDate": "2024-05-01T23:59:00-04:00[America/New_York]"
    }
}

Error Handling

The APIs use standard HTTP status codes to indicate success or failure:

Common Status Codes

• 200: Successful operation
• 400: Invalid request parameters
• 401: Authentication failure
• 403: Forbidden (insufficient permissions)
• 404: Resource not found
• 429: Too many requests (rate limit exceeded)
• 500: Internal server error

Error Response Format

{
    "status": 400,
    "message": "[ID=abcd] BAD REQUEST: InvalidInputFormatException: Invalid customerId format: 'null'."
}