WorkOS Postman collection

Postman is a popular API development tool that allows users to easily test API endpoints. The WorkOS API collection is a set of pre-configured requests specific to the WorkOS API, meant to help developers to quickly get started testing the WorkOS API endpoints.

The environment template supports this collection, and allows variables to be abstracted away from the individual requests. The environment template makes it easier to manage and re-use common variables across the collection’s requests.

There are several ways to use this collection. You can create a fork, or you can export/import the collection and environment.

The preferred and simplest way to get started using the WorkOS API collection is to create a fork of the collection and environment.

To create a fork of the collection, first sign in to your Postman account. Then navigate to the WorkOS API collection. Hover over the name of the collection and click the three dots, then click “Create a fork”.

Select your fork label and workspace, then click the “Fork collection” button.

You will now see the WorkOS API collection appear in your workspace’s collection tab.

To fork the WorkOS environment template, the same process is used. Navigate to the environments tab of the WorkOS Public workspace. Hover over the WorkOS environment template, click the three dots, and then click “Create a fork”. Select your fork label and workspace, then click the “Fork environment” button.

Another way to use the WorkOS API collection is to import the collection and environment into your workspace. Using this approach allows you to share the collection as a JSON file to easily share it with others.

To export the collection, navigate to the collection tab in the WorkOS workspace, then hover over the WorkOS API collection name and click on the three dots. Click export to download the collection as a JSON file.

Navigate to your workspace’s collections tab and click on the import button.

Select the JSON file that was downloaded in the previous step and then click import. You will now see the collection available to use and edit in the collection tab.

The environment can be exported from the WorkOS workspace and imported to your personal workspace using these same steps.

Navigate to the collection tab in your workspace and select the environment. This allows the collection to reference the environment variables.

The WorkOS API collection makes use of environment variables. All environment variables that are used in the WorkOS API collection are defined in the environment tab in Postman.

To get started, you will need to obtain the api_key and client_id values from your WorkOS dashboard and enter them in the environment template.

You can find your API key and the client ID on the API Keys page in the WorkOS dashboard.

There are also several other environment variables in the template which will need to be replaced with various IDs and values in the course of making API calls. These values are defined in the variable descriptions.

The WorkOS collection sends data in several ways. Some requests use values directly in the URL, some requests use query parameters, and some requests send data in the body of the request. Each call will indicate where there are values present with a green dot.

The “Get A Directory User” request for instance uses the api_key environment variable in the authorization tab of the request, and the base_url and directory_user_id values in the URL of the request.

The “Generate a Portal Link” request uses the base_url and api_key variables in the same way that the Get A Directory User call does, but also sends the name of the Organization and intent in the body of the request as x-www-form-urlencoded data.

To send a request, first select the WorkOS environment template so the collection has access to its variables.

Finally, ensure all the values are defined where they are needed for the particular request and then click send.

Postman provides a developer console if you need to debug any requests. Navigate to a request and click on the console button to view the details of the requests you send.

If you have any questions while using the WorkOS API collection, please reach out to our team at support@workos.com.