GLPI API v2 OAuth2 integration: setup and planning

How the GLPI High-level API v2 with OAuth2 connects your systems to GLPI

A team that needs scripts or connectors to read or write GLPI data should build them on the High-level API v2, which authenticates with OAuth2 bearer tokens issued from /api.php/token. The legacy REST API is not the starting point for new work. The integration pattern is the same whether the caller is an inventory script, a service desk connector or a reporting job: register an OAuth client in your GLPI instance, request a token with the grant type that matches the caller, then call the API with that token and only the scopes the caller needs.

The supported grant types split by who is acting. A password grant suits a service account acting on behalf of a named GLPI user, while an authorization code grant suits applications where a person signs in and approves access. The inventory scope is designed for GLPI Agent inventory submission through the client credentials grant, so it is the scope to check first for device data pipelines. The graphql and api scopes cover the query and resource endpoints, and email, user and status cover narrower lookups. Confirm the current grant and scope list against the API documentation before you write the client, because the set may change between releases.

Everything in this design runs inside your own GLPI deployment. The OAuth clients, token lifetimes, service accounts and scopes are configured on your server, and the tokens never leave your network unless you send them there. Tokens expire after one hour by default, and the lifetime can be changed with GLPI_OAUTH_ACCESS_TOKEN_EXPIRES in config/local_define.php. Plan that setting, and the refresh behavior of each client, before the first integration goes live, because short lifetimes change how long-running jobs must handle re-authentication. Read the GLPI RESTful API (V2) documentation for the exact endpoints and settings.

What a GLPI API v2 integration needs before the first token request

Most failed first token requests trace back to the GLPI instance, its web server, or the path between the integration host and GLPI rather than to the OAuth code itself. Work through these checks with the GLPI owner, the network team and the identity owner before anyone registers a client.

Confirm the GLPI version and API v2 availability

Start by recording the exact GLPI release in production, such as the 11.0 line or the 12.0 line, and check in the official documentation that High-level API v2 is available and documented for that release. Do not assume that a version which runs the core application also exposes the v2 endpoints. Record the answer in the integration design so that the upgrade plan can test it again later.

Match PHP and database versions

The GLPI README on the main branch lists PHP 8.3 or later with MariaDB 10.11 or later or MySQL 8.0 or later, while the installation docs for GLPI 11.0 list PHP 8.2 or later with MySQL 8.0 or MariaDB 10.6. Use the requirements that match your release and confirm the exact minimums before you build the integration host. The docs state that only MySQL and MariaDB are supported.

Expose GLPI over HTTPS

OAuth2 token and API calls must reach GLPI on a stable HTTPS address that clients can resolve and trust. The web server document root must point to GLPI's public directory with URL rewriting to index.php, on Apache, Nginx, lighttpd or IIS. Confirm the certificate chain is trusted by every integration host, since a self-signed certificate often passes in a browser and fails in a service account.

Plan OAuth client registration rights

Decide which administrator registers OAuth clients and who approves them, because a client grants API access under a chosen scope set. Keep the client registration rights separate from day-to-day ticket administration where your access model requires it. Ask the GLPI owner to document who can rotate client secrets and who can review scopes such as inventory, graphql and api.

Map the network path to GLPI

List every host that will request tokens or call the API, including agent relays, middleware and CI runners, and confirm each can reach the GLPI hostname on the HTTPS port. Check reverse proxies, load balancers and firewall rules in both directions, and note whether traffic crosses a DMZ or a separate network zone. Document the path so the team can diagnose timeouts without guessing.

Protect the configuration and keys

Plan where the local configuration file that sets the token lifetime will live, and who may edit it. Back up the GLPI encryption key files before changes, since the update procedure treats glpi.key and glpicrypt.key as required backup items. Record each change in the change log so that a restore brings back the same integration settings.

Configuring the OAuth client and first API call in sequence

This sequence takes an integration from an enabled High-level API v2 to one authenticated read call. Each step produces a record or check that the next step depends on, so the scope boundary and token lifetime are settled before any integration code is written.

Confirm API v2 is enabled on the instance
Confirm that your GLPI release provides the High-level API v2 and that it is enabled on the instance, following the steps in the GLPI RESTful API (V2) documentation. The GLPI administrator does this in the administration area, and the exact location depends on the release you run. Check that the token endpoint at /api.php/token answers on your instance URL. A response that asks for credentials confirms the endpoint is reachable and ready for client registration.
Register the OAuth client and record its secret
Register an OAuth client for each integration in the GLPI administration area, giving it a name that identifies the system and its owner. Record the client identifier and client secret in your secrets manager before you leave the registration screen, because the secret authenticates the integration. Do not share one client across unrelated integrations, so you can rotate or revoke one without affecting the others. Check that the client appears in the list with its identifier and that your secrets manager returns the stored secret.
Choose the grant type for each integration
Match each integration to one grant type. Use the client credentials grant for system-to-system work such as GLPI Agent inventory submission, which relies on the inventory scope. Use the password grant only when a dedicated service account must act as a user, and accept that the integration then handles that account's password. Use the authorization code grant when a person must sign in and consent to the access. Check that a short decision record lists each integration, its grant type and its owner, and that no integration is left without one.
Request only the scopes the integration needs
The API v2 documentation lists the scopes email, user, status, inventory, graphql and api. Request the smallest set for each client. Inventory exists for GLPI Agent submission through the client credentials grant, so a reporting integration has no reason to hold it. Add graphql only when the integration queries through GraphQL. Check that the scopes in the client configuration match the decision record, and confirm in a test environment that a request for a scope the client does not hold is refused.
Set the token lifetime only when justified
Tokens expire after one hour by default. Leave that value unchanged unless a specific integration has a documented reason to change it, such as a long batch job that cannot renew its token. To change it, set GLPI_OAUTH_ACCESS_TOKEN_EXPIRES in config/local_define.php and record the change in your change log. Shorter lifetimes limit how long a leaked token stays useful but increase renewal requests. Check that the expiry in the next token response matches the value you set, or shows the one-hour default if you changed nothing.
Request an access token from the token endpoint
Send a token request to /api.php/token on your instance with the grant type, client identifier, client secret and the scopes from the decision record. Run the request from the host that will run the integration so you test the real network path. Keep the request and response out of application logs and shell history. Check that the response contains an access token, a token type and an expiry, and that the expiry matches the lifetime you expect from the previous step.
Make one scoped read call
Send a read request to a GLPI endpoint covered by one of your scopes, passing the access token in the Authorization header as a bearer token. Choose a read that returns a record you already know, such as the service account's own user record or one computer you can verify in the interface. Then repeat the call without the token and with a scope the client does not hold. Check that the known record returns the values you expect and that both out-of-scope calls are refused, which confirms the scope boundary before you build on it.

Password or authorization code grant, and which scope to request

Use this path for scheduled jobs, middleware and service-to-service integrations that read or write GLPI records without a person behind each call. The integration authenticates as its own identity, so audit entries show the service account rather than a human. That makes ownership of the account, its profile and its entity access the main control to get right, because every action is attributed to it.

Identity: the token represents the integration itself, so rotate its credentials on a schedule your team owns and document who can change them.
Audit: GLPI history will show the service account for each change, so agree on how downstream systems record the originating job or ticket.
Scopes: request api and graphql only when the job needs them, and add user or status only for the specific lookups it performs.
Access: pair the account with a restricted GLPI profile and entity scope, since the token inherits the permissions of the account it runs under.
Lifetime: confirm the default token expiry in the official documentation and decide whether shorter lifetimes fit your job schedule.

Before building, confirm which grant types your GLPI release supports in the official API documentation and check that the service account can be scoped as described.

Use this path when a tool acts on behalf of a signed-in person, such as a front-end portal or a desktop client where staff view their own tickets or assets. The authorization code grant lets the user approve access, so GLPI records actions against that person's identity and their existing profile. The trade-off is that the tool depends on a browser redirect and a registered callback, which adds setup work for every client.

Identity: each action reflects the user who consented, which fits audit requirements for personal data access.
Audit: log entries tie to the individual, so reviews can follow a user's actions through the tool.
Scopes: user and email fit profile and contact lookups, while api covers general record access.
Access: the tool can see only what that user's GLPI profile and entities allow, which limits the blast radius of a compromised client.
Consent: agree how users revoke access and how the tool handles expired sessions without storing long-lived credentials.

Confirm in the official documentation which grant types and redirect rules your release supports, and test the consent screen with a non-administrative account.

Use this path for GLPI Agent submitting hardware and software inventory. The agent runs on endpoints, has no user session, and authenticates through the client credentials grant with the inventory scope, which is reserved for inventory submission. Its trade-off is that a single agent credential should not be reused for other API work, since its scope and purpose are narrow by design.

Identity: each agent or deployment group should use its own client so a compromised endpoint can be revoked without affecting others.
Audit: inventory submissions appear under the agent's client, which helps trace which deployment sent a given record.
Scopes: request inventory alone for agents, and do not add api or graphql to the same client.
Rollout: plan credential distribution through your configuration management, and keep secrets out of images and shared scripts.
Rotation: plan how agents receive new credentials when the client is rotated across a large fleet.

Check the agent documentation for how it is configured to obtain a token, and confirm the inventory scope behavior in the official GLPI API documentation for your release.

Scopes are the main control on what a token can do, so request each scope only when a named integration task needs it. The six scopes are email, user, status, inventory, graphql and api. Each one unlocks a different kind of access, and the narrowest set is easier to justify in an access review and easier to revoke.

email: reads or uses email address data, needed for notification and contact lookups.
user: exposes user records and their attributes, which carries personal data exposure.
status: covers status information about the instance or resources your integration checks.
graphql: allows queries through the GraphQL endpoint, useful for shaped reads but a separate surface to review.
api: covers general REST-style record access, the broadest scope in this list.

Map each integration to a written scope list before build, and confirm in the official documentation what each scope permits in your release.

How scopes and GLPI objects map to integration tasks

This table maps each GLPI API v2 scope to the integration task it usually serves, the identity the call runs as, and the data it can reach. Read the last column as a checklist: the scope sets the type of access, while the OAuth client user's entities and profile rights set the actual reach. Confirm those rights in GLPI before any token is issued.

Scope	Typical integration task	Identity and data it can touch
email	Sending or matching user contact details for notification or lookup tasks	Runs as the OAuth client user. Confirm which email fields the scope exposes and under which entity rights.
user	Syncing user records from an HR or directory source, or reading requester details	Runs as the OAuth client user. Confirm whether the profile allows create and update as well as read.
status	Reading or setting status on tickets, assets or other items from an external tool	Runs as the OAuth client user. Confirm which itemtypes the scope covers and which items the profile can access.
inventory	Submitting hardware and software inventory from GLPI Agent through the client credentials grant	Runs under the client credentials identity and writes inventory data. Confirm the target entity and the rights needed to create inventory records.
graphql	Querying linked objects in one request for reporting, dashboards or sync jobs	Reads what the OAuth client user can see across the requested types. Confirm that field access and query scope follow profile rights.
api	General access to GLPI items for scripts and connectors that need broad read and write	Broadest access, bounded by the OAuth client user's profile and entities. Confirm rights and test with a least-privilege user before granting it.
Entity and profile rights	Checking each scope against the client user before go-live	The scope grants a type of access, but the GLPI profile and entity assignment decide what is visible and writable. Record the result for each client.

Securing OAuth clients, tokens and the GLPI instance

An API v2 integration is only as safe as the OAuth client that holds its credentials, the scopes that client can request, and the logs that show what it did. The cards below cover those controls in the order a team usually meets them, from secret handling to audit. Instance-level session and key handling is covered separately in GLPI security hardening.

Client secret storage and rotation

Each OAuth client secret is a standing credential for whatever the integration can reach, so it should live in a secrets manager or an encrypted store on the calling host, never in source control or a shared script. Record which system holds each secret, who can read it, and when it was last rotated. Build rotation into the integration so a new secret can be issued and the old one retired without a code change. Confirm in your own GLPI instance how client secrets are displayed and whether they can be regenerated without deleting the client.

Least-privilege scopes per client

Request only the scopes the integration needs: for example, user for reading user records or status for a status check, rather than a broad grant. Create one OAuth client per integration so a compromised script exposes only its own scopes and can be disabled without affecting others. Review scope assignments whenever the integration changes, because scope creep usually happens through small additions. Check the scope list against the current GLPI API v2 documentation before you approve a client.

Token lifetime trade-offs

Access tokens expire after one hour by default, which limits the damage from a leaked token. Lengthening the lifetime through GLPI_OAUTH_ACCESS_TOKEN_EXPIRES in config/local_define.php reduces token requests but widens the window in which a stolen token works. Shortening it adds token traffic and failure handling in long batch jobs. Choose a value per integration, document the reason, and test how your client renews tokens when a request returns an expired-token error.

HTTPS-only transport

Bearer tokens and client credentials are only as protected as the connection that carries them, so every call to the token endpoint and the API must use HTTPS with valid certificates. Reject plain HTTP at the reverse proxy, disable redirects that drop the Authorization header, and make sure clients verify certificates rather than skipping checks in test code. Confirm that the URL configured for GLPI in each integration matches the public address served by your web server.

Separating inventory submission from user scopes

The inventory scope exists for GLPI Agent submissions through the client credentials grant, so it should belong to a machine-only client used by agents. Do not grant it to a client that also reads or changes tickets, and do not reuse a user-facing client for agent traffic. Keeping these paths apart means an agent credential cannot read user data, and a user-facing integration cannot write inventory. Document which client belongs to which purpose before rollout.

Auditing API activity

Record which client and scope made each request, when it was made, and what it changed, then send those records to your central log platform. Review failed token requests and unusual volumes from a single client, since these often reveal a leaked secret or a broken script. Confirm which API events GLPI logs natively in your version and what you must add at the proxy or integration layer. Set a retention period that matches your internal policy and ask your security team to own the review.

Why token requests and API calls fail

This table lists the failures teams most often hit when requesting OAuth2 tokens and calling GLPI High-level API v2, with the likely cause and the fix for each. Read it when a token request or API call returns an error, and match the symptom to the row before changing configuration.

Symptom	Likely cause	Fix
Token request rejected with invalid client	Client ID or secret copied incorrectly, or the client was registered for a different grant type than the one requested	Confirm the client ID and secret in GLPI's OAuth client settings, regenerate the secret if unsure, and match the grant type the client was registered for
Token request returns unauthorized for inventory calls	Client credentials grant used without the inventory scope, or the scope was never granted to the client	Request the inventory scope only for GLPI Agent style submissions, and add the scope to the registered client before retrying
Calls return forbidden after a token is issued	Token carries a scope that does not cover the endpoint, such as user or email scope used against inventory or graphql	Decode the scopes on the token, then request the scope the endpoint needs and check the account's GLPI profile permissions
Calls start failing about an hour after issue	Access token expired, since the default lifetime is one hour	Refresh or request a new token before each batch, or raise the lifetime with GLPI_OAUTH_ACCESS_TOKEN_EXPIRES in config/local_define.php and restart the client's token cache
Token endpoint returns 404 or an HTML page	Web server document root points to the GLPI installation root, or URL rewriting does not route /api.php to index.php	Point the document root to GLPI's public directory and confirm rewrite rules on Apache, Nginx, lighttpd or IIS so the /api.php path resolves
Requests work in a browser but not from scripts	Reverse proxy strips headers or path segments, or base URL in GLPI does not match the public address clients use	Check the public URL configured in GLPI against the address clients call, and confirm the proxy forwards the full path and Authorization header
Integration still calls the legacy REST API	Existing script or connector was written for API v1 and was never moved to v2, so it fails or is blocked after the change	Inventory each script and connector, map its calls to v2 endpoints, and plan the move before disabling the legacy API in your environment
Token works on one GLPI version and fails after an upgrade	Client registration or configuration was lost during the update, or the upgrade changed how the API is exposed	Confirm the OAuth clients and local_define.php settings survive the update, and rerun a test token request after the upgrade and plugin reactivation

Questions teams ask before building a GLPI API v2 integration

How much effort does a GLPI API v2 integration take to build?

Effort depends mainly on how many scopes, grant types and target workflows the integration needs, not on a fixed size. A read-only reporting connector that uses one client and one scope is far smaller than a bidirectional sync that creates tickets, updates assets and reads user records. Each additional workflow adds mapping, error handling, permission testing and a test case. Ask any partner for a quote built from a written list of workflows, the scopes each one needs and the GLPI instances involved, because that list is what moves the estimate up or down.

What does our team need to provide before the build starts?

The build needs four things from your side: administrator access to the GLPI instance so OAuth clients can be registered, named data owners who can confirm which tickets, assets or users the integration may touch, a non-production GLPI test instance with realistic data, and a place to store client secrets such as your existing secrets manager. Without the test instance, validation tends to happen against production, which slows approvals. Confirm access paths and change windows early, since they often set the schedule more than the code does.

Can our in-house team build a GLPI API v2 integration without a partner?

A team with solid OAuth2 experience and GLPI administration skills can build a narrow integration in-house. The skills that are easy to underestimate are the grant choice (password or authorization code), scope design so the client holds only what it needs, token refresh and expiry handling, and testing that permissions behave as intended across entities and profiles. If those skills are thin, or the integration must be documented for an audit, an external implementation partner can take on design and handover. Weigh the internal time against the ongoing upkeep described below.

How long does validation take for a GLPI API v2 integration?

Validation time depends on your environment more than on the API itself. The main drivers are how many GLPI instances or entities must be tested, whether your identity and network paths reach GLPI the same way in test and production, how many approval steps your change process requires, and whether security testing of the integration is part of the scope. Ask for a validation plan with explicit exit criteria rather than a single duration, and confirm the timing of each approval gate with your own change board.

What ongoing work comes with a GLPI API v2 integration?

Two things recur. The first is credential upkeep: client secrets and tokens must be rotated on a schedule your security policy sets, and the token lifetime is set in configuration, with the default described in the GLPI API v2 documentation as one hour. The second is GLPI upgrades. Each major release can change API behavior, and since GLPI 11 plugins are suspended after an update is detected until they are reactivated, plugin-dependent integrations need retesting after each upgrade. Budget for both in your operating model and ask any provider how they will handle them under a retainer or internal rota.

When do we still need the legacy GLPI REST API?

Keep the legacy REST API for existing scripts and connectors that have not been moved yet, and for any integration that depends on a capability not yet exposed through v2. The High-level API v2 uses OAuth2 only, so every integration must register a client and handle tokens. Plan the move as a separate workstream: inventory existing connectors, check each for the endpoints and data it reads or writes, then rebuild them on v2 and retire the old credentials. Confirm the current coverage of v2 with GLPI's documentation and the vendor before deciding which connectors can move first.

What should we confirm with GLPI before committing to v2?

Confirm the exact scopes available in your GLPI version, including email, user, status, inventory, graphql and api, and which ones your use case requires. Check whether the inventory scope, which GLPI Agent uses through the client credentials grant, fits your agent deployment. Verify the token endpoint path, the token lifetime setting and how it is configured in your installation, and confirm whether your GLPI edition or subscription changes what the integration may do. Record the answers in the design document so the auditor and the next maintainer can see the basis for each decision.

Which security controls matter most for a GLPI API v2 client?

The most important controls are narrow scopes, separate clients for separate workflows, secrets kept outside source code, short-lived tokens, and logging of which client performed which change. Give each client a dedicated GLPI profile with only the rights it needs, so a compromised client cannot reach unrelated entities. Test that the profile limits hold, not just that the integration works. Confirm your secrets storage, rotation process and log retention with your security team before the first production token is issued.

When the legacy REST API is still needed

Keep existing scripts and connectors on the legacy REST API only until you have a dated plan to move them, because the High-level API v2 is where GLPI's OAuth2-based integration work is documented and where new scopes such as inventory, graphql and api are defined. The decision to keep a legacy integration running during transition depends on four things: whether the client or product that calls it can be changed, whether the data it reads or writes is available through a v2 endpoint with the same behavior, whether the credential model it uses can be replaced by an OAuth client, and who owns the code once the original author has left. A script that only reads asset lists may move quickly. A connector that writes to tickets, relies on a specific legacy field or runs on a schedule nobody documented usually needs a longer parallel run.

Map each legacy integration before you register any OAuth client. For every one, record the calling host, the API user and profile, the endpoints and fields used, the authentication method, and the failure behavior. Then check each item against the v2 documentation for your installed GLPI version, because GLPI 11 and 12 differ in what they ship. Confirm with your own test instance, not from memory, that the v2 endpoint returns the same fields and enforces the same entity and profile rights. Also confirm how long the legacy API stays enabled in the release you run, and whether your planned GLPI 11 or 12 upgrade changes it. Keep the legacy path reachable only from the systems that still need it, and log its use so you can see when the last caller has gone.

The step-by-step migration of scripts and connectors, including token handling changes and cutover, is covered in the sibling topic on REST API v1 versus High-level API v2, so this section is limited to deciding what stays. Treat the keep-or-move list as a deliverable with an owner and a review date. Where a vendor product only supports the legacy API, ask that vendor in writing for its support plan for v2 and for the GLPI version it certifies, rather than assuming the integration will follow the core upgrade. Keeping a legacy integration is a acceptable short-term position, but it should be a recorded exception with a retirement condition, not the default.

How DeployOpen scopes and delivers GLPI API v2 integrations

DeployOpen plans, builds and hands over GLPI High-level API v2 integrations inside infrastructure you control. We start from the systems that need to call GLPI, the scopes they need and the token lifetime your security policy allows, then build and test the OAuth2 flow in your environment before anything reaches production.

How we scope

We list each calling system, the GLPI data it reads or writes, and the API scopes that access requires.
We confirm which grant fits each client, password or authorization code, and document why.
We record token lifetime, client registration owners and any legacy REST API dependencies in the written scope before work starts.

How we build

We register OAuth clients in your GLPI instance and configure the scopes agreed in the scope document.
We set token lifetime in config/local_define.php and test renewal behavior against your expiry policy.
We test each flow, including inventory submission and GraphQL queries, against a non-production GLPI copy before go-live.

How we hand over

We deliver integration code, client registration records, configuration notes and a runbook for rotating client secrets.
We document each scope, its purpose and the systems that hold its credentials so your team can review access.
We walk your engineers through the test results and the plan for moving any remaining legacy REST API scripts to v2.

How we support

Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
Ongoing support, GLPI upgrades and continuous testing are available as a retainer, including checks after each GLPI update.
Ask us to confirm which parts of the integration your own team will own after handover, and record that split in the scope.

GLPI High-level API v2 integration with OAuth2