Make REST API requests

1Password SaaS Manager provides pre-configured workflows for a range of APIs but sometimes there's an API call you want to make that SaaS Manager doesn't support. We're always keen to get feedback requests to extend our integrations, but what if the API is one that we don't support or is perhaps an in house application? 

Simple worked example

To make a REST API request, create a workflow, then add an API request step.

API requests have three main elements:

1. Request – the URL, any data to send, and how authentication is handled
2. Response – what to do with the data returned by the API call
3. Errors – how to handle any errors that may occur

The simplest request is just a plain HTTP GET to a URL with no authentication. In our example, we will use https://catfact.ninja/fact which returns a JSON structure like this:

{
    "fact": "Miacis, the primitive ancestor of cats, was a small, tree-living creature of the late Eocene period, some 45 to 50 million years ago.",
    "length": 133
} 

Clicking Test request will run the request, and if successful, take you through to the Response tab.

Processing responses

The Response tab will show you the JSON returned by the request. Currently SaaS Manager supports processing JSON and binary responses.

Responses can be transformed using a language called JMESPath. JMESPath isn't hard to learn, but LLMs are very good at generating JMESPath which provides a quick way to get the right syntax.

In our example, we will leave the JSON as it is (using @). However we want to put the results into two output variables fact and length.  To do so:

1. Click Add output and then choose to Add new field...
2. Create a new text field called 'Fact' and enter fact as the Source value JMESPath expression. The dialog will show you the result of evaluating the JMESPath.
3. Click OK and then repeat again for a Number field called 'Length' with the JMESPath length.

These fields can now be used as merge fields in subsequent workflow actions like sending emails or Slack messages.

Making a second request with a path parameter

Type in the URL https://cataas.com/cat/says/Length is {{Length}}

Notice how as you type the double braces you get shown fields you can enter. You can also click the {{f}} button to the right of the URL field to view all fields.

On the Response tab click Binary as the Expected format.

Finally we'll put this together by sending an email. Add a new step to the workflow and select Send email. Be sure to check the API request response box.

Now run the workflow. You can view the request details and the response details for each step. You should also receive an email to confirm that the workflow ran correctly.

Authentication

The API request action supports three authentication methods directly:

• Basic Auth
• HTTP Header – allows you to specify the header name, and optionally add the commonly used Bearer prefix
• OAuth – OAuth2 Client Credentials flow

Most of the above are self-explanatory but OAuth has more complexity.

OAuth2

OAuth is a more complicated but superior protocol to Basic Auth or HTTP headers. There are different variants, and the API request action supports the most common one for 'machine to machine' communication: "Client Credentials". 

With Basic Auth or HTTP headers, every HTTP request includes the credential which increases the likelihood that it might be written to a log or be leaked somehow.

OAuth Client Credentials flow has a separate authentication step which (if successful) returns a fresh token which expires after a short period of time (typically up to 60 minutes). If this token leaks then there is much less risk because it has likely expired by the time someone finds it.

Because the protocol is more complicate there is a standard way for applications that implement this to describe the settings they support. This is the .well-known/openid-configuration endpoint. 

The Authority is the URL where this endpoint can be found. The reality is that many vendors do not implement this, but you should use it where possible as it will make configuration easy.

In this example, we will use in the Tailscale endpoint: https://api.tailscale.com/

When you click Test, SaaS Manager tries to determine if there is a valid .well-known/openid-configuration endpoint. In this case none is found, so you have the option now to directly enter the Access Token URL. This is listed in the Tailscale API documentation which also describes how to obtain the Client identifier and Client secret. In this case you must configure an OAuth client within the Tailscale app.

The final two fields on the dialog Client authentication and Scopes are sometimes used and give you a little more control over how the Client Credentials flow is carried out. Client authentication lets you choose how the credentials are sent (OAuth supports doing this as part of the body of the HTTP post, or as headers). Some applications support one or the other, many support both, but you may have to change this depending on what the API documentation specifies. Scopes describe what access you require. Many applications don't require this because, like Tailscale, when you configure the OAuth client you define which scopes will be granted at point of configuration rather than at point of authentication.

Press Save, and now configure your API request as usual.

Clicking Test request will run the request, authenticating first behind the scenes using OAuth.

Advanced OAuth settings

These should rarely be needed but are provided for completeness. An example would be where the .well-known/openid-configuration file doesn't quite match what the token endpoint expects and you might need to turn off validating the issuer name or endpoints.

Authenticating with Microsoft Graph API endpoints

The Authority for Microsoft Graph is https://login.microsoftonline.com/{tenantId}

If you enter this (substituting {tenantId} for your Entra tenant ID) and click Test. SaaS Manager will confirm that it's worked with a green checkbox. However, if you go on to test a request, you will get an error explaining that the discovery document does not match the authority.

You could fix this using the Advanced settings described above, but the root cause is that the .well-known/openid-configuration discovery document (for compatibility and legacy reasons) points to the older Microsoft Graph authentication endpoints.

To use the newer endpoint, you should enter an invalid Authority, allowing you to specify the Access Token URL directly. e.g. specify the Authority as https://login.microsoftonline.com (without the tenant id in the path), click Test and then enter the following URL: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token.

Note that this endpoint also requires the scope https://graph.microsoft.com/.default

With this in place you should be able to test a request successfully.

Handling errors

By default, any response code other than an HTTP 20X will result in the "Error" sub-path in the workflow being followed.You can change these rules to add up to 2 specific paths for different error classes, as well as ignoring certain errors.

For example, to ignore HTTP 404, switch to the Errors tab and click Add output. Enter 404 for the response code and choose Ignore as the action. Or you could add a specific action for an HTTP 409.

With more complex flows you may want to move the step to a group. This will mean that different paths can execute, but when they are complete the group will be completed and the main workflow moves forwards.

This helps where you want to continue on the main path after an error has been handled. Click the vertical ellipsis icon in the API request step, then click Add to group to do so.