How to make API Requests

In addition to the target environment, the name of the application is also needed and must be sent in each request as the following header.

X-Servitly-Tenant: acme

Except for a few methods, before calling any API it is required to perform a login in order to obtain a JWT token that is exchanged on each subsequent API call.

The login can be done by using one of the following alternatives:

• Username and Password: this is the standard login based on the user credentials and suitable, for instance, into third-party frontend applications or Mobile applications.

• PAT: this is the login based on Personal Access Token that is recommended for cloud to cloud integration.

Moreover, to identify the client performing an API call, you need an API Key, that can be configured within the target environment, for more details refer to the API Keys article.

The obtained JWT token has a limited duration, and when expired, it must be renewed, or a new login must be performed.

Into the body of the login response you can find:

• token: the JWT token to be sent as Bearer token

• refreshToken: the token required to renew the JWT.
  Note that the JWT can be refreshed only when expired.

• userId: the ID of the authenticated user.

• tenantId: the ID of the target tenant.

{
 "token": "eyJhbGciOiJIUzUxMiJ9.eyJsYX.....",
 "refreshToken": "cd5352cd-b297-4149-95e5-deac47c56324",
 "userId": "667ca382a6128f46aad59ee3",
 "tenantId": "661233a837504726e531d68b"
}

Authentication with PAT

To make an API request to the DPS, a JWT token must be obtained, using the login endpoint.
Instead of using the standard user login endpoint, it is necessary to use the PAT-based login endpoint.

POST https://<API_BASE_URI>/identity/users/patLogin
X-Semioty-Tenant <TENANT_DOMAIN>

{
 "apiKey": "<API_KEY>",
 "pat" : "<PAT>"
} 

Note that using a PAT also requires an API key, which must be configured with the right permissions.

Using Python

Here is reported a sample Python script that uses a PAT to login and retrieve the user identity.
Optionally you can use the login with user credentials (see commented part).

Be careful to substitute the tenant-name, use the right login PAT, API Key, and point to the desired environment.

import requests

baseUrl = "https://api.servitly.com/"
apiKey = "<API_KEY>"
pat= "<PAT>"

headers = {
    "X-Semioty-Tenant": "<TENANT_NAME>"
}

# Login with user credentials
# print("==== Login with user credentials ====")
# url = baseUrl +  "identity/users/login?apiKey=" + apiKey
# data = {"email": "<email>", "password": "*****"}
# response = requests.post(url, headers=headers, json=data)
# auth = response.json()


# Login with PAT
print("==== Login with PAT ====")
url = baseUrl +  "identity/users/patLogin"
data = {"apiKey": apiKey, "pat": pat}
response = requests.post(url, headers=headers, json=data)
authResponse = response.json()


# Read the JWT token
print(response)
print(authResponse) 
if "token" in authResponse: 
  headers["Authorization"] = "Bearer " + authResponse["token"]
else:   
  quit()  

# Get the user identity
print("\n\n==== Get user identity ====")
url = baseUrl +  "identity/users/me"
response = requests.get(url, headers=headers)
print(response.json())

Using CURL

Here is reported a sample script (Linux and Window) that uses the CURL command to perform the login, store the token in a local file and finally retrieve the user identity by performing an authenticated API call.

Be careful to substitute the tenant-name, use the right login credentials, and point to the desired environment.

curl --location --request GET "https://api.servitly.com/identity/users/me" 
--header 'Authorization Bearer <JWT_TOKEN>' \
--header 'accept: application/json' \
--header 'X-Semioty-Tenant: <TENANT_NAME>'

Testing Tools

If you want to test API invocation, you can use one of the tools described in this article.