Central Configuration via API

An application programming interface (API) defines how a client application communicates with a service. HPE Aruba Networking Central exposes configuration and operational capabilities through REST APIs, enabling network teams to build repeatable automation and integrate Central with external systems.

Central is powered by the HPE GreenLake platform and uses a microservices architecture to manage campus, branch, remote, and data center networks. Central APIs provide programmatic access to configuration, monitoring, inventory, troubleshooting, and other platform services.

This section introduces the Central REST API implementation and the resources available for developing automation. A WLAN deployment example demonstrates how to translate the configuration model described in the Central Configuration Model section into a PyCentral workflow.

API-First Architecture

Central REST APIs are designed as part of the platform and provide access to configuration and operational capabilities. As Central capabilities are added, the API reference provides the resource paths, request-body schemas, and response models used to integrate those capabilities with applications and automation platforms.

This approach provides network teams with consistent methods to:

• Automate repetitive configuration and operational tasks.
• Apply configuration consistently across multiple sites and device types.
• Integrate network operations with external applications and orchestration tools.
• Validate changes and retain results in a repeatable workflow.

REST APIs

Central configuration APIs follow the Representational State Transfer (REST) architectural style and use standard HTTP methods to operate on network resources. An API operation combines an HTTP method with a resource path. A request also can contain headers, query parameters, and a request body. The response contains an HTTP status code, headers, and, when applicable, a response body.

Refer to the Central REST API getting-started guide for the current request methods, status codes, base URLs, and usage limits.

API Client Credentials and Access Tokens

Central uses OAuth 2.0 client credentials to obtain access tokens. Every Central API request requires a bearer access token in the HTTP header using the Authorization: Bearer <access-token> format. An access token generated from Central credentials has the same rights and permissions as the Central user role of the user who created those credentials.

Use the HPE GreenLake Manage Workspace page to create a Personal API client for either the Central instance or the HPE GreenLake Platform (GLP). The credential type determines the token endpoint and lifetime.

Central does not provide an OAuth refresh token or an automatic renewal mechanism. When an access token expires, the client must request a new token using its client ID and client secret. When client credentials are supplied, PyCentral automates that new-token request.

Follow the Developer Hub instructions for creating credentials and generating access tokens.

API Base URL

The Central API base URL depends on the cluster where the account is provisioned. In Central, open Menu > API Gateway > REST API to copy the base URL for the account. The Developer Hub also maintains the current API Gateway base URL list.

Status Codes and Rate Limits

Common response codes include:

Central currently documents an account-wide limit of 10 API requests per second. The limit is shared by all client credentials and tokens in the account.

Resources for Automation Development

The HPE Aruba Networking Developer Hub provides Central guides, API references, Postman collections, and PyCentral documentation.

Note: The Developer Hub contains resources for both Central and Classic Central. This guide uses the current Central APIs. Some Developer Hub URLs and repositories retain the term New Central to distinguish them from Classic Central.

Postman Collections

Postman provides a graphical environment for exploring and testing APIs. Central publishes two official collections:

• MRT APIs for monitoring, reporting, and troubleshooting.
• Configuration APIs for Central configuration resources.

Both collections use OAuth 2.0 and share the same Central Postman environment. Each collection maintains its own access token, so authenticate the MRT APIs and Configuration APIs collections separately. Fork the official collections and environment by following the Central Postman collection guide.

Postman is useful during the initial development of a workflow to:

• Review request paths, headers, query parameters, and request bodies.
• Test authentication and permissions before writing code.
• Examine response bodies and status codes.
• Save a successful request as the basis for an automation workflow.

PyCentral SDK

PyCentral is the official Python SDK for Central and GLP APIs. It manages authentication and provides reusable classes and methods for common API operations. PyCentral v2 supports the current Central and GLP APIs as well as compatibility modules for Classic Central.

PyCentral is useful for network administrators who want to move a request tested in Postman into a repeatable Python workflow. It reduces the amount of code required for authentication, scope discovery, profile operations, pagination, and response handling.

Note: PyCentral version 2 remains a prerelease. Review the PyCentral release notes and validate the installed version before using it in a production workflow.

Central Python Workflows

The central-python-workflows repository contains self-contained Central and GLP automation examples. The profile operations workflow demonstrates individual and bulk configuration-profile operations with the Profiles class.

The repository uses prerelease PyCentral v2 packages. Treat the workflows as examples. Review their requirements and validate the request paths and payloads against the API reference and the PyCentral version installed in the execution environment.

Best Practices for API Configuration Automation

• Prototype a request in Postman or the Developer Hub before adding it to a script.
• Use the current Central API reference as the source for paths, query parameters, and request-body schemas.
• Pin the PyCentral prerelease used by a production workflow and test before upgrading.
• Transmit API requests only over HTTPS, and do not disable TLS certificate validation.
• Keep API client credentials, access tokens, and configuration secrets outside source control.
• Validate a configuration change with a subsequent GET request.
• Log the operation, resource path, response status, and request or correlation ID when returned. Do not log access tokens, client secrets, passphrases, or sensitive response data.

Configuration with PyCentral SDK

PyCentral SDK Package Structure

The following directory listing is from PyCentral 2.0a25. It shows the available starting points for Central, GLP, Classic Central, MSP, monitoring, configuration profile, scope, streaming, and troubleshooting workflows.

pycentral/
├── __init__.py
├── base.py                         # NewCentralBase client
├── classic/                        # Classic Central compatibility modules
│   ├── __init__.py
│   ├── audit_logs.py
│   ├── base.py
│   ├── base_utils.py
│   ├── configuration.py
│   ├── constants.py
│   ├── device_inventory.py
│   ├── firmware_management.py
│   ├── licensing.py
│   ├── monitoring.py
│   ├── msp.py
│   ├── rapids.py
│   ├── refresh_api_token.py
│   ├── topology.py
│   ├── url_utils.py
│   ├── user_management.py
│   ├── visualrf.py
│   └── workflows/
│       ├── __init__.py
│       └── workflows_utils.py
├── exceptions/                     # SDK exception classes
│   ├── __init__.py
│   ├── login_error.py
│   ├── parameter_error.py
│   ├── pycentral_error.py
│   ├── response_error.py
│   └── verification_error.py
├── glp/                            # HPE GreenLake Platform services
│   ├── __init__.py
│   ├── devices.py
│   ├── service_manager.py
│   ├── subscriptions.py
│   └── user_management.py
├── msp/                            # MSP and tenant connections
│   ├── __init__.py
│   ├── msp_base.py
│   └── tenant_base.py
├── new_monitoring/                 # Central monitoring modules
│   ├── __init__.py
│   ├── aps.py
│   ├── clients.py
│   ├── constants.py
│   ├── devices.py
│   ├── gateways.py
│   ├── sites.py
│   ├── switches.py
│   └── wlans.py
├── profiles/                       # Configuration profile operations
│   ├── __init__.py
│   └── profiles.py
├── scopes/                         # Sites, site collections, devices, and groups
│   ├── __init__.py
│   ├── device.py
│   ├── device_group.py
│   ├── scope_base.py
│   ├── scope_maps.py
│   ├── scopes.py
│   ├── site.py
│   └── site_collection.py
├── streaming/                      # Central streaming APIs and event models
│   ├── __init__.py
│   ├── streaming.py
│   └── events/
│       ├── __init__.py
│       ├── alert/
│       │   ├── __init__.py
│       │   └── alert_pb2.py
│       ├── ap/
│       │   ├── __init__.py
│       │   └── ap_events_pb2.py
│       ├── audit/
│       │   ├── __init__.py
│       │   └── audit_trail_pb2.py
│       ├── client/
│       │   ├── __init__.py
│       │   └── client_pb2.py
│       ├── event/
│       │   ├── __init__.py
│       │   └── event_pb2.py
│       ├── geofence/
│       │   ├── __init__.py
│       │   └── geofence_pb2.py
│       ├── location/
│       │   ├── __init__.py
│       │   └── location_pb2.py
│       ├── location_analytics/
│       │   ├── __init__.py
│       │   └── location_analytics_pb2.py
│       └── switch/
│           ├── __init__.py
│           └── sw_pb2.py
├── troubleshooting/                # Central troubleshooting operations
│   ├── __init__.py
│   └── troubleshooting.py
└── utils/                           # Shared SDK helper functions
    ├── __init__.py
    ├── base_utils.py
    ├── common_utils.py
    ├── constants.py
    ├── glp_utils.py
    ├── monitoring_utils.py
    ├── profile_utils.py
    ├── scope_utils.py
    ├── troubleshooting_utils.py
    └── url_utils.py

For current Central workflows, the most commonly used modules are:

API Call Models

PyCentral provides two ways to call Central APIs:

• SDK methods: Use classes such as Profiles when PyCentral provides a method for the operation.
• Direct API calls: Use NewCentralBase.command() when you need to call an endpoint that does not have an SDK method.

For example, this direct API call retrieves up to 10 devices:

response = central_conn.command(
    api_method="GET",
    api_path="network-monitoring/v1/device-inventory",
    api_params={"limit": 10},
)

Use api_params for values added to the URL, such as limit. Use api_data for the request body, usually with POST, PUT, or PATCH requests.

For supported profile operations, the Profiles class provides a higher-level method.

created, response = Profiles.create_profile(
    path=profile_path,
    config_dict=profile_data,
    central_conn=central_conn,
    bulk_key=None,
)

The same NewCentralBase session is passed to each SDK method. PyCentral v2.0a15 and later support using this session as a context manager, which closes the persistent HTTP client when the workflow completes.

See the PyCentral authentication guide for supported credential models.

See the PyCentral quickstart for installation and direct API call examples.

PyCentral SDK Deployment Example

The following procedure creates a shared, bridged WPA2-Personal WLAN SSID profile, validates the profile with a read operation, and assigns it to an existing site with the Campus Access Point device function. It uses the Profiles class for profile operations and the SDK scope model for site assignment. Since the script does not supply local-object query parameters, the Configuration API creates a shared profile by default.

The WLAN endpoint is documented in the Create a new WLAN SSID profile API reference. Review that reference whenever adding or changing WLAN attributes.

The validation operation uses the Read an existing WLAN SSID profile API.

Note: This example was validated against PyCentral 2.0a25, which requires Python 3.10 or later.

Summary of Steps

Step 1 Confirm the Central account and WLAN prerequisites.

Step 2 Create a Python virtual environment and install the required packages.

Step 3 Add the Central API client credentials.

Step 4 Define the WLAN profile and target site.

Step 5 Create and run the deployment script.

Step 6 Validate the profile assignment and effective configuration.

Prerequisites

Before running the example, ensure that:

• The target site already exists in Central.
• The APs are onboarded, provisioned for Central, assigned to the target site, and online.
• The Central user role associated with the API client credentials permits profile creation, scope lookup, and profile assignment.
• The role referenced by default-role already exists and is appropriate for the WLAN.
• VLAN 101 exists in the campus network and is carried on the AP uplink path for bridged forwarding.

Install the Packages

Step 1 Open a terminal in the directory used to store the example.

Step 2 Confirm that Python 3.10 or later is installed, then create and activate a virtual environment.

python3 --version
python3 -m venv venv
source venv/bin/activate

Step 3 Create a requirements.txt file with the following content.

pycentral==2.0a25
PyYAML>=6.0.3,<7.0

The ==2.0a25 pins PyCentral to that exact version. Pinning means recording the version that the example was tested with, so a later installation does not silently use a different version and produce different results. The PyYAML entry allows compatible versions from 6.0.3 up to, but not including, 7.0.

Step 4 Install the packages.

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

For evaluation of the newest prerelease instead of a repeatable build, the Developer Hub uses python -m pip install --pre pycentral. Pin the version after validation to make subsequent runs repeatable.

Configure Central Credentials

Before continuing, make sure you have the Central API base URL and the client ID and client secret for a Personal API client that has access to the Central instance.

Step 1 In the example directory, create a file named .gitignore. Add the following entries so Git does not include the virtual environment, credentials, or WLAN configuration in a commit.

venv/
account_credentials.yaml
wlan_config.yaml

Step 2 In the same directory, create a file named account_credentials.yaml and add this template.

new_central:
  base_url: "<api-base-url>"
  client_id: "<central-client-id>"
  client_secret: "<central-client-secret>"

Step 3 Replace the three placeholders with the values issued for your Central instance:

• <api-base-url>: the Central API base URL.
• <central-client-id>: the Personal API client ID.
• <central-client-secret>: the Personal API client secret.

Define the WLAN Profile

Step 1 Create wlan_config.yaml with the following content.

wlan:
  ssid: "SecureWiFi"
  enable: true
  type: "EMPLOYEE"
  ap-mode: "CAMPUS_AP"
  forward-mode: "FORWARD_MODE_BRIDGE"
  essid:
    name: "SecureWiFi"
  opmode: "WPA2_PERSONAL"
  personal-security:
    passphrase-format: "STRING"
    wpa-passphrase: "<replace-with-a-valid-passphrase>"
  default-role: "<existing-client-role>"
  vlan-selector: "VLAN_RANGES"
  vlan-id-range:
    - "101"

targets:
  sites:
    - "NYCCP-CNX"

Step 2 The wlan object is sent as the request body. The first site in targets.sites is used as the assignment scope in this example.

Create the Deployment Script

Step 1 Create wlan_deploy.py with the following content.

#!/usr/bin/env python3
"""Create a shared WLAN profile and assign it to an existing Central site."""

import sys
from urllib.parse import quote

import yaml
from pycentral import NewCentralBase
from pycentral.profiles import Profiles
from pycentral.utils.url_utils import generate_url


def error_text(response):
    """Return a printable error without assuming a specific response shape."""
    if not isinstance(response, dict):
        return str(response)
    message = response.get("msg", response)
    if isinstance(message, dict):
        return message.get("message", str(message))
    return str(message)


def load_configuration(path):
    """Load and validate the minimum inputs required by this example."""
    with open(path, "r", encoding="utf-8") as config_file:
        config = yaml.safe_load(config_file) or {}

    wlan = config.get("wlan") or {}
    sites = (config.get("targets") or {}).get("sites") or []
    if not wlan.get("ssid") or not sites:
        raise ValueError("wlan.ssid and at least one targets.sites entry are required")

    return wlan, sites[0]


def main():
    try:
        wlan, target_site = load_configuration("wlan_config.yaml")
    except (OSError, ValueError, yaml.YAMLError) as error:
        print(f"Unable to load wlan_config.yaml: {error}")
        return 1

    ssid = wlan["ssid"]
    encoded_ssid = quote(ssid, safe="")
    profile_path = generate_url(api_endpoint=f"wlan-ssids/{encoded_ssid}")

    try:
        with NewCentralBase(
            token_info="account_credentials.yaml",
            log_level="CRITICAL",
            enable_scope=True,
        ) as central_conn:
            print(f"Creating WLAN profile: {ssid}")
            created, create_response = Profiles.create_profile(
                path=profile_path,
                config_dict=wlan,
                central_conn=central_conn,
                bulk_key=None,
            )
            if not created:
                print(f"WLAN profile creation failed: {error_text(create_response)}")
                return 1

            print("Verifying the WLAN profile with a GET request")
            verified, verify_response = Profiles.get_profile(
                path=profile_path,
                central_conn=central_conn,
            )
            if not verified:
                print(f"WLAN profile verification failed: {error_text(verify_response)}")
                return 1

            sites = central_conn.scopes.get_all_sites()
            site = next(
                (site for site in sites if site.get_name() == target_site),
                None,
            )
            if site is None:
                print(f"Target site not found: {target_site}")
                return 1

            profile_resource = f"wlan-ssids/{ssid}"
            print(f"Assigning {profile_resource} to site: {target_site}")
            assigned = site.assign_profile(
                profile_name=profile_resource,
                profile_persona="CAMPUS_AP",
            )
            if not assigned:
                print(f"Profile assignment failed: {profile_resource}")
                return 1

    except Exception as error:
        print(f"Central operation failed: {error}")
        return 1

    print(f"Assigned WLAN profile {ssid} to site {target_site}")
    return 0


if __name__ == "__main__":
    sys.exit(main())

Step 2 Review the script before execution. It performs the following API operations:

• Creates the shared WLAN SSID profile.
• Reads the profile to verify that Central accepted the configuration.
• Assigns the profile to the target site for the CAMPUS_AP device function.

The Central UI uses the term device function. The scope-map API and PyCentral use the term persona for the corresponding API value. In this example, the Campus Access Point device function maps to the CAMPUS_AP persona.

The example creates the profile, reads it to verify the configuration, and then assigns it to the target site. A production workflow should first decide whether to create it, update it, or leave it unchanged.

Run and Validate the Example

Step 1 Confirm that the following files are in the same working directory.

demo/
├── .gitignore
├── account_credentials.yaml
├── requirements.txt
├── venv/
├── wlan_config.yaml
└── wlan_deploy.py

Step 2 Run the script.

python wlan_deploy.py

Step 3 Confirm that the script reports successful profile creation, verification, and assignment.

Step 4 In Central, open the target site and verify that the WLAN profile is assigned to the Campus Access Point device function.

Step 5 Confirm that the intended APs inherit the profile and that no scope with higher precedence changes the effective configuration. For more information, see Understanding Inheritance.

Troubleshooting

When an API operation fails, record the status code and response without recording credentials or passphrases. The following table lists common causes.