Configuring ManageEngine Service Desk Plus

The ManageEngine ServiceDesk Plus Cloud (SDP OnDemand) v3 API authenticates with Zoho OAuth 2.0. A ServiceDesk Plus login on its own cannot call the API — every request carries a short-lived access token minted from a refresh token, and that refresh token is issued when an OAuth client is granted consent.

Setting up a connection therefore has two one-time steps in the Zoho API console — registering an OAuth client and generating an authorization code — followed by the guided flow on the Precision Bridge connection form, which exchanges that code for a refresh token. No command-line requests are required.

Data Centre URLs

ServiceDesk Plus Cloud is hosted in several data centres. Two fields on the connection are data-centre specific: the API Base URL and the Accounts Server. Use the row matching the data centre your account is hosted in.

The API Base URL is the host only (without /api/v3); the adaptor appends the API path itself.

Data centre	API Base URL	Accounts Server	API console
UK	https://servicedeskplus.uk	https://accounts.zoho.uk	https://api-console.zoho.uk
EU	https://sdpondemand.manageengine.eu	https://accounts.zoho.eu	https://api-console.zoho.eu
US	https://sdpondemand.manageengine.com	https://accounts.zoho.com	https://api-console.zoho.com

Other data centres (India, Australia, Japan, Canada, and others) follow the same pattern with their own Zoho domain suffix. If you are unsure of your data centre, check the domain you use to sign in to ServiceDesk Plus.

Registering an OAuth Client

Register a Self Client in the Zoho API console for your data centre. A self client is intended for server-to-server access and does not require a redirect URL.

1. Sign in to the API console for your data centre (see the table above).
2. Select Add Client, choose Self Client, and confirm.
3. Open the Client Secret tab and note the Client ID and Client Secret. These are reused for every connection to this account and do not expire.

Required Scopes

Scopes control which modules the connection may access. They take the form SDPOnDemand.<module>.<operation>, where the operation is one of READ, CREATE, UPDATE, DELETE, or ALL. Combine multiple scopes with commas.

For example, to read and write requests and read configuration data:

SDPOnDemand.requests.ALL,SDPOnDemand.setup.READ

Grant the narrowest set of scopes that covers the modules your project uses (for example requests, problems, changes, assets, solutions).

The scopes on the refresh token determine which tables the connection can read. A token scoped only for SDPOnDemand.requests.ALL can extract from the Requests table but returns an authorization error for other modules. To work with additional modules, include their scopes when generating the authorization code.

Generating an Authorization Code

The authorization code is a short-lived, single-use value that the connection form exchanges for a refresh token.

1. In the API console, open the Generate Code tab of your self client.
2. Enter the scopes from the previous section.
3. Set a short duration (for example 10 minutes) and a description.
4. Generate the code, select the ServiceDesk Plus portal if prompted, and copy the code.

Generate the code immediately before creating the connection, because it expires within minutes.

Creating the Connection

1. In Precision Bridge, open the Connections page and select New Connection.
2. Choose the ManageEngine Service Desk Plus adaptor.
3. Enter a Name for the connection.
4. Enter the API Base URL and Accounts Server for your data centre.
5. Enter the Client ID and Client Secret from your self client.
6. Under Get a refresh token, paste the authorization code and select Get refresh token. Precision Bridge exchanges the code with Zoho and fills in the Refresh Token field.
7. Save the connection, then select Test to verify it.

The connection does not have a scope field. Scopes are fixed when the authorization code is generated and travel with the refresh token, so there is nothing further to configure.

How Authentication Works

When you select Get refresh token, Precision Bridge sends the authorization code to your data centre's Accounts Server and receives a long-lived refresh token, which is stored with the connection. From then on, Precision Bridge uses that refresh token to mint short-lived access tokens automatically as they expire — the authorization code is not needed again. ServiceDesk Plus requests carry the access token using Zoho's Zoho-oauthtoken authorization scheme.

Because the refresh token is stored on the connection and does not expire, the code-generation step is performed only once per connection. If the refresh token is revoked in the Zoho console, generate a new authorization code and repeat the Get refresh token step.

Network Access

The machine running Precision Bridge must be able to reach two hosts over HTTPS (port 443): the Accounts Server (to mint tokens) and the API Base URL (to call the API). Only outbound access is required. If Precision Bridge runs behind a firewall or proxy, allow outbound connections to both hosts, or configure a proxy on the connection (see API Connections).

Troubleshooting

• invalid_code — the authorization code has expired or has already been used. Generate a new code and retry.
• invalid_client — the Client ID or Client Secret is incorrect, or the Accounts Server does not match the data centre where the client was registered.
• No refresh token returned — the code was not generated with the required scopes, or it expired before exchange. Generate a fresh code and retry.

See Also

• Creating Connections
• API Connections