Modernizing Maximo Integrations with the Manage REST API and API Keys

# Modernizing Maximo Integrations with the Manage REST API and API Keys

Enterprise asset management platforms do not operate in isolation. They sit at the center of an ecosystem that includes ERP systems, IoT platforms, GIS tools, scheduling applications, mobile apps, and now AI agents. For IBM Maximo customers, the integration story has changed significantly with the move from Maximo 7.6 to the Maximo Application Suite (MAS). The Integration Framework (MIF) still exists, but the recommended path is now the API-first design built around the Maximo Manage REST API, OSLC resources, JSON payloads, and API key authentication.

This article explains how to design, build, and secure integrations in MAS 9.2 using the Manage REST API. It covers the architecture shift from SOAP to REST, how API keys work, how to query and write data through object structures, and what organizations should do to make their integrations reliable, observable, and ready for the agentic AI workflows that MAS 9.2 introduces.

The Integration Architecture Has Changed

For years, Maximo integrations were dominated by MIF, enterprise services, publish channels, SOAP web services, and XML. These mechanisms still work in MAS, but they are no longer the center of the integration model. MAS introduces a different philosophy: API-first design, event-driven architecture, standards-based protocols, and cloud-native middleware. The goal is to make Maximo behave like any other modern enterprise application that exposes well-documented, stateless, JSON-based endpoints.

There are practical reasons for this shift. SOAP services require more overhead to maintain. XML parsing is verbose. Basic authentication embedded in integrations creates security risk. Session-based authentication does not scale well across cloud deployments and serverless consumers. The Manage REST API addresses these issues by providing a lightweight, OSLC-compliant interface that supports JSON, URL-friendly query parameters, and API keys.

The Maximo mobile application and the new desktop UI framework in MAS are both built on the JSON API. That fact alone is a strong signal: the REST API is the path that IBM is investing in for the future of the product. Teams that continue to build new integrations on legacy REST endpoints or SOAP should at least evaluate migration, especially as they plan MAS upgrades.

Understanding the Manage REST API

The Maximo Manage REST API is a complete rewrite of the older REST interface introduced in the 7.1 and 7.5 era. It has been integrated into Maximo Manage since version 7.6.0.2 and is the supported API surface in MAS. It exposes two primary resource types: Maximo Business Objects (MBOs) and Integration Object Structures (OS).

MBO resources allow direct interaction with business objects such as ASSET, WORKORDER, and LOCATION. Object structure resources are the preferred integration path because they provide a stable, configuration-driven contract. An object structure defines the shape of the data being exchanged and can include parent and child objects, lookups, and aliases. Using object structures insulates consumers from the underlying MBO schema and allows administrators to control data exposure through security groups.

A typical read request looks like this:

code block

The `lean=1` parameter requests the clean JSON format without XML namespaces. The `oslc.where` parameter filters records using OSLC syntax. The `oslc.select` parameter restricts the returned fields. These parameters are important for performance and maintainability. Returning every field on every record is expensive for both the server and the integration consumer.

For writes, object structures support POST, PUT, MERGE, and DELETE operations. A create request for a work order through the MXAPIWODETAIL object structure might look like this:

code block

code block

In MAS, the base URL depends on the deployment topology. For a MAS Manage deployment, the endpoint typically follows the pattern:

code block

The exact path and authentication flow depend on whether MAS is configured for native authentication, LDAP, or SAML/OIDC. Teams should consult their MAS installation documentation for the correct route.

API Key Authentication in MAS

One of the most important changes when moving to MAS is authentication. In legacy Maximo, integrations often used MAXAUTH headers with base64-encoded usernames and passwords, or BASIC authentication through the application server. In Maximo Application Suite, the supported methods for the Manage REST API are OIDC/SAML and API keys. API keys are the practical choice for most integration scenarios because they work consistently across authentication backends and do not require user sessions.

An API key is a token associated with a specific Maximo user. It acts in the context of that user, meaning all security groups, object structure permissions, site restrictions, and data restrictions apply. The login is silent: no MAXSESSION record is created. This makes API keys ideal for batch jobs, middleware flows, mobile backends, and AI agents that need to call Maximo repeatedly without interactive login.

Administrators can create API keys through the Administration Work Center under Integration > API Keys. They can also be created programmatically. In MAS 9.2, the recommended path is to use the API key creation endpoint with an authenticated session:

code block

code block

The expiration value is in minutes. A value of -1 means the key never expires, which is convenient but should be reserved for tightly controlled service accounts. The response returns an `apikey` string that must be stored securely.

To use the key in subsequent requests, pass it as a header:

code block

Or as a query parameter, although the header is preferred for security:

code block

If administrators need to manage keys for other users, the MXAPIAPIKEY object structure can be used:

code block

code block

And to list or revoke keys:

code block

A few system properties govern API key behavior. `mxe.apikeysysusers` can block specific users from creating keys. `mxe.apikeyforloggedinuser` restricts users to creating keys only for themselves. `mxe.allowexternalapikey` can disable the feature entirely. Reviewing these properties should be part of any integration hardening exercise.

Object Structure Security

Exposing Maximo data through an API is only safe if access is controlled. Object structure security is the mechanism that determines which users and security groups can interact with which object structures. In legacy Maximo, this security could be bypassed in some configurations, leading to overexposed data. The system property `mxe.int.enableosauth` enforces explicit grants, meaning users must be assigned to object structures through their security group.

Before enabling this property in production, organizations should audit their integrations. Identify every external system that calls Maximo. Map each one to the object structures it actually needs. Create dedicated service accounts and security groups rather than reusing personal credentials. This improves traceability and makes it easier to revoke access when an integration is decommissioned.

A practical hardening checklist includes:

- Set `mxe.int.enableosauth` to 1.
- Verify that all consumed object structures are explicitly granted.
- Create dedicated API users with minimal permissions.
- Issue API keys with short expiration windows where possible.
- Store keys in a secrets manager, never in source control.
- Revoke keys when integrations are retired.

Object structure access is stored in the `APPLICATIONAUTH` table, just like application security. Database administrators can query this table to verify that grants match expectations.

Query Patterns for Integration Developers

The Manage REST API supports a rich set of query options. Mastering these patterns reduces server load, improves response times, and makes integrations easier to maintain.

Filtering

The `oslc.where` parameter supports comparisons, logical operators, and related record filtering. For example, to find open work orders against critical assets in a specific site:

code block

Spaces and special characters must be URL-encoded. Many integration tools provide helpers for this, but developers should still understand the syntax.

Pagination

For large data sets, pagination is essential. The API supports `_pageSize` and `_offset` parameters, as well as next-page links in the response. A typical paged request:

code block

Integration jobs should respect pagination and avoid pulling entire tables into memory. For historical syncs, consider filtering on a changed timestamp or using a staging table approach.

Child Objects

Object structures can return child records inline. For a work order with labor, materials, and services, the consumer can request nested data by selecting the child collection. The exact syntax depends on the object structure definition, but a typical request might look like:

code block

Testing these queries in a non-production environment is important. The response shape can change based on the object structure configuration, and poorly written queries can return large payloads.

Bulk Operations and Asynchronous Integration

Not every integration should use synchronous REST calls. For high-volume data exchange, MIF and the Maximo Integration Framework still have a role. Bulk imports through flat files, enterprise services, and publish channels can be more efficient than thousands of individual REST calls. The key is to choose the right tool for the job.

A common hybrid pattern is:

- Use REST APIs for interactive, low-latency, event-driven integrations.
- Use MIF for high-volume bulk imports and exports.
- Use message queues or event streams for durable, asynchronous workflows.

In MAS, event-driven integration can be supported by IBM Event Streams, Kafka, or cloud-native message brokers. When an asset status changes, a Maximo automation script can emit an event to a topic. Downstream consumers react without polling. This reduces load and improves responsiveness.

Here is a simplified automation script pattern that could publish an event after a work order status change. This is illustrative and should be adapted to your event infrastructure:

code block

The exact script language and binding depend on the Maximo version and scripting engine configuration. Always test automation scripts in a sandbox before promoting them.

Integrating AI Agents with the MCP Server

MAS 9.2 introduces an important integration capability for the AI era: the Model Context Protocol (MCP) Server. This allows external AI agents to connect to Maximo Manage APIs in a governed way. Instead of every agent needing custom integration logic, the MCP Server provides a standard interface through which agents can discover available tools, gather context, plan actions, and execute API calls.

The MCP Server follows a five-step loop: gather context, plan, evaluate, act, and observe. External systems such as Slack, Google Workspace, third-party platforms, and community MCP servers can participate. For Maximo customers, this means an AI agent could, with proper authorization, query asset history, create work orders, or update inventor

...