Advanced

To get started using the Lytx API, authenticate yourself by generating an access token. The token gives you access to the API operations. If you make a request using an API operation that you don't have access to, an error is returned. The token must be created via user registration using Postman.

Requirements

• Postman Desktop App
• Git for Windows
• Lytx Account credentials for a 'Full Access' user at the highest group level. For detail on creating users, go to Managing Users.
• (For Groups API write endpoints) Lytx Account credentials for user with 'Full Access' and 'Group Manager' roles at the highest group level.

Before You Begin

The Customer Collection.postman_collection.json collection must be downloaded and imported into your local workspace.

Instructions

1. If the user to register does not have a public key, generate one. Open git-bash in Windows Search Bar and run these commands in order. This generates a public and private key pair inside the lytx_keys folder. Suggested Script:

mkdir lytx_keys
cd lytx_keys
openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -outform PEM -pubout -out public.pem

2. In this scenario, the public.pem file contains the public key. Save or copy the public.pem file to Postman's working directory. You can check where it is in: Postman App > Settings > General > Location
3. If the Customer Collection from the Before You Begin section has already been imported, select it in Postman. Select Customer Collection.postman_collection.json. In the Variables tab, update the my_username and my_password with the Lytx Account user credentials. Save your changes.
4. Click on the User Registration folder, then click the Run icon in the top right.
5. In the Runner dialog, checkmark Persist Responses for a Session in the bottom-right, then click the Run button. Verify all tests passed.
6. Click on the POST Register User call to see the response. The values (header and payload) will be needed in the next section. These values can also be found in the Variables tab of the Customer Collection.postman_collection.json.

Generating An Access Token

To complete registration, you need to generate a JSON Web Token. For that, you need the following:

• Header
• Payload
• Private Key
• Public Key With the data above, the header and payload would be as follows:

Header sample:

{
  "alg": "RS256",
  "typ": "JWT",
  "iss": "4XMeH767NxCuPZCzWjlHu98aeU1126IN"
}

Payload sample:

{
  "name": "kongtestuser",
  "user_id": "0000ffff-0000-1b00-71ca-ed46b0d60000",
  "co_id": "1129",
  "rootgroupid": "2bb2d9b4-c801-e111-81ce-e61f13277aab",
  "roles": "Developer",
  "exp": 1701887152
}

To generate the access token, proceed as follows

1. Go to JWT.IO.
2. For Algorithm, select RS256.
3. Insert the Header and Payload from above. Note that the "exp" field is defaulted to 1 month, but can be adjusted according to the account's security policy.
4. Navigate to and open your Public and Private Keys, previously created, in a text editor. Copy the entirety of the Public Key, to include ---BEGIN PUBLIC KEY--- and ---END PUBLIC KEY--- and replace the content in the top box under Verify Signature. Repeat the same for the Private Key into the bottom box.
5. Once Signature is Verified in the bottom-left, your token is the encoded token on the left. Copy this into the Postman Customer Collection variables under Current Value for thirdparty.access-token. This token is the key component for authorization when calling the GET Short Lived Token.
6. Call the GET Short Lived Token request to receive your signed token. This bearer token will lasts 60 minutes. If this step is successful, you will not need to repeat steps 1-5 until the time your JWT expires.
7. Copy the token’s value only, select the appropriate API call you’d like to make on the left hand side, click Try It in the top right corner, past the token under Bearer Token, ensure all required parameters (marked with an asterisk) are met and any optional parameters are valid, click send.