JWT Bearer

Implemented using the JWT Bearer OAuth2 flow, this method is tailored for server-to-server scenarios. It allows secure access to the API without user interaction, leveraging token-based authentication for enhanced security.

Zylo requires a JWT that is signed using RSA SHA256, which uses an uploaded certificate as the signing secret. Keep this in mind when following the below steps.

1. Creating a Connected App

Pre-requisites

You must have "admin" permission in the Zylo application.

Connected Apps in Zylo are used to create the permissions, client_id, and client secret needed to exchange for the OAuth2 JWT Bearer access token.

In the Admin page within the Zylo application, find the "Connected Apps" tab.

Select the "Create Connected App" button to open up the "Create Connected App" modal.

Select "JWT Bearer" from the dropdown, select which permissions you want, and put in your X.509 Certificate that will be used to authenticate your requests.

📘
Important Note
Make sure your X.509 Certificate corresponds to the private key used to sign your JWT.

After creating the connected app, you can edit it at any time to update your permissions.

2. Creating a JWT to retrieve an access token

When creating a JWT that will be used to retrieve an access token, be sure to sign with RSA SHA256 and include the following claims as defined in RFC7523 specifications:

Parameters	Description
iss	The issuer of the JWT, which must be the `client_id` of the Connected App that was created in the prior step.
sub	The subject of the JWT, in this case it would match the value for `iss`.
aud	The intended audience, which must be the authorization server’s token endpoint (`https://api.zylo.com`).
exp	The expiration time of the JWT, expressed as a Unix timestamp (Epoch time). Must be within the allowable time window.

The Content-Type for the request must be set to application/x-www-form-url-encoded.

Below is an example using your JWT to retrieve an access token:

curl --request POST \
  --url https://api.zylo.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
  --data assertion={JWT}

The response is a JSON object that includes three values:

access_token: The OAuth2 JWT Bearer access token (JWT) used to authorize against Zylo API resources.
token: The token type, always returns "bearer".
expires_on: The time (Epoch Unix Timestamp) in which the access token will expire.

3. Using the OAuth2 JWT Bearer access token

The OAuth2 Access Token is included in the Authorization request header for all authenticated API resources.

Below is an example using the OAuth2 JWT Bearer access token in a request:

curl --request GET \
  --url https://api.zylo.com/v2/applications \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json'