Skip to content

Introduction

ServicePlaza provides you a REST-based API to manage and configure your instance.

What can you do with it?

  • Synchronize assets with any element manager system (create new assets, update existing assets, or remove them)
  • Create new catalog order from your service catalog.
  • Add a new ticket to the system.
  • Update your phone numbers according to their usage.

Module Structure

ServicePlaza is a modular structured system. Every microservice will provide its API endpoints that are related to their responsibilities.

How to use the API?

This chapter will help you to work with ServicePlaza API to get started with it.

Base URL

ServicePlaza API endpoints will be based on your ServicePlaza instance FQDN. In a cloud-based environment this will be for example:

https://<customer>.serviceplaza.io/<servicename>/

Replace \<customer> with your instance name.

Depending on the API endpoint to use, the \<servicename> will differ. Please find below the list of available services:

service servicename
Inventory Management sp-inventory
(Service) Catalog sp-catalog
Order Management sp-order
Workflow sp-workflow
Invoice sp-invoice
Helpdesk sp-helpdesk
Basic Services (Web-Frontend) leave \<servicename>/ parameter blank

Authorization

ServicePlaza will use the Identity Provider (IdP) system Keycloak to authenticate users and API requests. Any request in ServicePlaza will need a valid OAUTH 2.0 token for authentication.

In Keycloak authentication system an API user with required permissions must be created to use the OAUTH2 client grant flow.

To get a valid token, you´ll have to send a HTTP POST to the URL:

https://auth.<customer>.serviceplaza.io/realms/ServicePlaza/protocol/openid-connect/token

The HTTP body of the request should look like the following:

{
  “grant_type” : “client_credentials”,
  “client_id” : “<CLIENT_ID>”,
  “client_secret” : “<CLIENT_SECRET>”
}

While creating the API user in Keycloak you´ll get the data for \<CLIENT_ID> and \<CLIENT_SECRET>. Please make sure to keep this data save and secure.

The response of the HTTP POST request will look like this:

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ0N01ZWVcwcjdSajViWTB2X1lOMlhGU1NDRXJSX1ZCQ0Jwb0NYVGg5M25jIn0.eyJleHAiOjE2OTkyNTYyMDUsImlhdCI6MTY5OTI1NTkwNSwianRpIjoiNGFmYTAxY2ItYWUzNi00OTQwLWE1YmYtODUxZjAzYjg3ZWJlIiwiaXNzIjoiaHR0cHM6Ly9hdXRoLmRlbW8uc2VydmljZXBsYXphLmlvL3JlYWxtcy9TZXJ2aWNlUGxhemEiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiZDQ0N2RhMDEtMzNhZi00NTVjLWEyNzYtZDZhYjBhMjJlMzEzIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoic2VydmljZXBsYXphLXdvcmtmbG93LXNjcmlwdC1jbGllbnQiLCJhY3IiOiIxIiwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJkZWZhdWx0LXJvbGVzLXNlcnZpY2VwbGF6YSJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwiY2xpZW50SG9zdCI6IjE3Mi4yMC4zLjEyIiwiY2xpZW50SWQiOiJzZXJ2aWNlcGxhemEtd29ya2Zsb3ctc2NyaXB0LWNsaWVudCIsInByZWZlcnJlZF91c2VybmFtZSI6InNlcnZpY2UtYWNjb3VudC1zZXJ2aWNlcGxhemEtd29ya2Zsb3ctc2NyaXB0LWNsaWVudCIsImNsaWVudEFkZHJlc3MiOiIxNzIuMjAuMy4xMiIsIlNQX1BFUk1JU1NJT05TIjoiU1BfSU5WRU5UT1JZX0FTU0VUU19SRUFEIFNQX0lOVkVOVE9SWV9BU1NFVFNfV1JJVEUgU1BfSU5WRU5UT1JZX0FTU0VUU19BUElfUkVBRCBTUF9JTlZFTlRPUllfQVNTRVRTX0FQSV9XUklURSBQSE9ORU5VTUJFUl9BUElfUkVBRCBQSE9ORU5VTUJFUl9BUElfV1JJVEUgVVNFUl9BUElfUkVBRCBTUF9JTlZFTlRPUllfQk9PS0lOR19BUElfUkVBRCBTUF9JTlZFTlRPUllfQk9PS0lOR19BUElfV1JJVEUgU1BfSU5WRU5UT1JZX0FTU0VUX0FMTE9DQVRJT05fV1JJVEUifQ.KVjXp0PI4LqX5dRCppTvlTijgfFGOmMDpMQosZAwM3TLVV7hKR4s9qNV11p3bmYK67Em4u-ebzKMgP6E1_iQm0lm7FkF0dDnvRRjie6z-U0BH0b3ed5AoLBe0DkklU9uExybsoo8kkZ9xzcfQ17Qf4AwdIk_tknlLTwsR1hdItPiggPd8Eo9BjAPfcrCloEzpcdCm6B1rX0pe2m5p5FehGnyNsmdt9mWKLrNe6ioR3h7qnDr6PXzga6T8UFVYp1A-zYeoL9CxZZB2HuvnbAVMrhqlIBb_Ickj7VGHdnHRQsqn3BQn28LThUUDUpXauhJXd-opvZiIUcjIUTJfVmPGA",
    "expires_in": 300,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 1674552126,
    "scope": "email profile"
}

Now use the access_token to authenticate your API requests in the HTTP Authorization header. The token value itself must be prepended with the word ‘Bearer ’.

Example: Bearer eyJhbGciOiJS....

You can also find working Python and PowerShell based code examples in the latest Workflow documentation.

Versioning

Please be aware that your ServicePlaza instance may use a different version then the documentation provided here. To check the available API endpoints in your instance a OpenAPI documentation spec is also provided in the following URLs depending on the API endpoint:

https:// <customer>.serviceplaza.io/<servicename>/swagger-ui/index.html