Postman collection with OpenID authentication

To test API endpoints, Pismo recommends you use a REST client, such as Postman. To help you with testing, Pismo provides a Postman collection and environment for a sample project. A collection is a group of API requests that can be arranged in folders inside Postman and saved to a file for future use. Postman also enables you to create your own environment for use with a collection. The collection can read from and write to variables in the environment. An environment can also be saved to a file for future use.

Click the following link to download a ZIP file containing the files for the sample project.

• Credit Card collection for OpenID – Demonstrates how to set up and manage a credit card account.

The ZIP file contains a collection file and an environment file in JSON format. A sample Organization (Org) already exists for the project.

📘

Make sure you read the Core objects section as well as the Authentication with OpenID section before working with the Sample project.

Write a program to generate JWTs

For OpenID authentication, you need a way to generate your own JWTs. You can do this by following these steps:

1. Follow the directions in Server authentication to generate a private key and a public key. In step 3 of the directions there, your customer representative sends you an API key (apikey). You use this key in the next section (Import the collection into Postman).
2. Using the directions in Creating a JWT, write a program for generating JWT tokens.
   The endpoints in the sample collection that start with "Get JWT for..." need to interface with this program to retrieve JWT tokens. These endpoints send a query to the local host at port 8082. For example, the endpoint Get JWT for Orgs group has the following URL:
   
   http://localhost:8082/?func=passportIntegration&group=pismo-v1:orgs:rw&tenantId=pismo-writerteam-TN-6aec6&accountId=pismo-writerteam-TN-6aec6&aud=https://identitytoolkit.googleapis.com/google.identity.identitytoolkit.v1.IdentityToolkit&sub=TN-6aec613f-44ba-4184-9488-bf0343e74734@pismo-tn-220624.iam.gserviceaccount.com&iss=TN-6aec613f-44ba-4184-9488-bf0343e74734@pismo-tn-220624.iam.gserviceaccount.com

Your program needs to accept the following parameters. (Alternatively, you can change the URL in the collection to match whatever parameters your program uses.)

Import the collection into Postman

1. Unzip credit.zip. You should have the following files.

   • Pismo credit program for OpenID.postman_collection.json - A Postman collection for the credit card program.
   • Sandbox for OpenID.postman_environment.json - A Postman environment file for the Pismo Sandbox.

2. Open Postman and go to Import > Choose Files.

3. Select Sandbox for OpenID.postman_environment.json and click Open. This loads the Sandbox for OpenID environment into My Workspace.

4. Click Environments in the left panel and then click Sandbox for OpenID.

5. Find "apikey" in the list of environment variables and paste your API key in the "Current Value" column. (This is the key that your customer representative sent you.)

6. Click Save.

7. Select "Sandbox for OpenID" from the drop-down menu in the upper right corner. This enables it as the active environment.

8. To import the credit card collection, go to Import > Choose Files and select Pismo credit program for OpenID.postman_collection.json. This loads the collection into My Workspace > Collections.

Test the endpoints

Most endpoints require values that are returned by other endpoints. The collection is set up so that if you call the endpoints in a set order, the necessary values are automatically saved to the Sandbox for OpenID environment and retrieved from that environment when needed.

For example, take a look at the following endpoint in the collection:

Authentication > Get JWT for Orgs group

With that endpoint selected, if you select the Tests tab in My Workspace, you should see the following code:

pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});
var jsonData = pm.response;
pm.environment.set("OrgsJWTtoRequestAccessToken", jsonData.text())

When the endpoint executes successfully, it returns a JWT token generated by your program. The last line in the above code block saves the JWT token to an environment variable named OrgsJWTtoRequestAccessToken.

If you click Environments in the left panel and then click Sandbox for OpenID to display the list of environment variables, you can find OrgsJWTtoRequestAccessToken in the list. Once you've stored a JWT token in this variable, any request that requires the token can retrieve it from there.

The next section lists the requests you need to run to test the endpoints in the credit card collection.

Quick reference

To test the endpoints in the credit card collection, execute the following requests in order. The sections following this one explain what these endpoints do.

📘

Before you run any of the endpoints, you need to execute the program that you wrote in Write a program to generate JWTs and leave it running in the background.

1. Authentication > Get JWT for Orgs group
2. Authentication > Generate access token for Orgs group
3. Platform > Programs > List Programs
4. Platform > Programs > Get program due dates
5. Authentication > Get JWT for Acquisitions group
6. Authentication > Generate access token for Acquisitions group
7. Platform > Acquisitions > Create an account application
8. Authentication > Get JWT for Accounts group
9. Authentication > Generate access token for Accounts group
10. Enduser > Accounts > Get account details

🚧

If you get the following error when you try to send a request, it probably means that you forgot to set the environment to "Sandbox for OpenID":

Could not send request
Error: getaddrinfo ENOTFOUND {{baseurl}}

The following sections explain these endpoints in detail.

Groups and access tokens

OpenID assigns endpoints to groups to control what data they can access. When you try to execute an endpoint that accesses data, you need to pass the name of a group in the request. This group name is embedded in an access token that you use to authenticate the request.

You use JWT tokens generated by the program you wrote earlier to generate access tokens. For each of the "Get JWT for..." endpoints in the Quick reference section, there is a corresponding "Generate access token for..." endpoint. The first endpoint generates the JWT token, and the second uses it to generate the access token. For example, you could run Get JWT for Orgs group to generate a JWT token, and then use it to generate an access token by running Generate access token for Orgs group. The resulting token contains the group name pismo-v1:orgs:rw.

An endpoint can belong to multiple groups. All endpoints belong to the two admin groups:

• pismo-v1:admin:rw – Read/write admin group
• pismo-v1:admin:ro – Read only admin group

If you use an access token that contains pismo-v1:admin:rw to execute an endpoint, it will have both read and write access to all project data. If you use an access token that contains pismo-v1:admin:ro to execute an endpoint, it will have read-only access to all data.

You could simply use one of these two groups to execute every endpoint, but that defeats the purpose of using OpenID. It's much safer to use a group that gives an endpoint access to only the data that it's intended for. For example, if you're trying to get the data for an account, you should use the pismo-v1:accounts:ro group. This allows the endpoint to read account data, but not alter it, and it can't access any data that isn't specific to accounts.

📘

For simplicity, the sample collection uses the "rw" versions of all the groups. In practice, you should use the "ro" version when an endpoint only needs read access.

Retrieve program data

Steps 1 and 2 in the Quick reference section create an access token for endpoints that are in the pismo-v1:orgs:rw group and store it in the Sandbox environment. The endpoints that access program data are in this group, so this enables you to execute the next three steps.

📘

Note that the accountId field for this endpoint is set to {{tenantId}}. Endpoints that access program data don't need to access a specific account, so you can use the tenant ID in place of the account ID.

Step 3 lists the programs that are included in the sample project. The endpoint stores the program ID for one of them in an environment variable. Step 4 retrieves the due date for that program and stores it in an environment variable. These stored values are needed for step 7.

Create an account

Steps 5 and 6 in the Quick reference section create an access token for endpoints that are in the pismo-v1:acquistions.rw group and store it in the Sandbox for OpenID environment. The endpoint that creates an account is in this group.

📘

Note that the accountId field for this endpoint is set to {{tenantId}}. The endpoint that creates an account is not accessing an account, so you can use the tenant ID in place of the account ID.

Step 7 creates a credit account and stores its account ID in the Sandbox for OpenID environment.

Retrieve account details

Steps 8 and 9 in the Quick reference section create an access token for endpoints that are in the pismo-v1:accounts.rw group and store it in the Sandbox for OpenID environment. The endpoints that access account data are in this group.

📘

In this case, the endpoint is accessing a specific account, so you need to set accountId to accounts.created.accountId.

Step 10 retrieves the data for the account that you created in step 7.