When in doubt about using OAuth 2.0, reach out to us! We've seen a lot of APIs and we've had a lot of practice setting this up. We can help you connect to your API quickly.
This should work for you!
Not all OAuth 2.0 implementations will work with this feature, but most should! When in doubt, reach out to us, and we can help you get connected to your API.
OAuth 2.0 is a secure standard that allows a user (you) to authenticate one service (your API) to interact with another service (Parabola) on behalf of the user.
Traditionally, a tool like Parabola would need to create separate implementations of OAuth 2.0 for each external service that it wanted to support. With our generic OAuth 2.0 feature, Parabola can be configured to connect to most API's that require OAuth 2.0!
Parabola only works with the Authorization Code Grant Type
Keep in mind that Parabola's OAuth2.0 feature only works with APIs that use the grant_type of Authorization Code. If you see a parameter called grant_type, and they would like you set to anything except authorization_code, then this will not work for your API.
OAuth 2.0 is a method in which Parabola (or any tool) obtains a bearer token to use to connect to an API. The token usually has a short life, generally around an hour, and each time it expires, Parabola will need to fetch a new token. That is done automatically with a refresh token that Parabola also keeps.
When a token is issued to Parabola from your selected service, that token can only be used by Parabola to pull the data that was specified when the token was generated. The refresh token can also only be used by Parabola and can only be used to refresh the specific token that Parabola has. It's a very secure system, which is why the set up process can feel complex.
For the purpose of this section, imagine that we are having a conversation with you. The following is a guide to the nouns we will use:
Youwill refer to you the user, the person setting this up in Parabola
The servicewill refer to the API/tool you are trying to connect to that is not Parabola
Parabolawill refer to, well, Parabola, the tool you are setting up the connection within.
Wewill refer to the authors of this document.
Setting up OAuth can be challenging. One way to make your life easier is to create a document and keep track of all the parameters, URLs, and tokens that you will be interacting with.
Be aware! Text editing programs like Google Docs and Microsoft Word will use 'single quotes' and "double quotes" that are not the same characters that APIs allow. So if you are recording bits of data in your document that have those characters, you may need to re-type them inside of Parabola to make sure that the correct character is in use.
All OAuth connections will require you to register an application with the service. Their documentation will provide instructions on how to go about doing that.
When you are registering your application, the service will ask for something along the lines of a Callback URL or a Return URI. Whatever variation of wording they use, you need to supply the service with this URL:
https://parabola.io/api/steps/generic_api/callback That is the URL that the service will use to send Parabola the access token for your account.
The service will provide you with at least two bits of information that we will refer to as your credentials. The service may give you more than just two, but there must be one that can serve as the
client_id and one that can serve as the
client_secret. Usually one will seem more secretive or password-like than the other. If they use different names, make your best guess as to which one is the secret and which is the ID. We believe in you!
Record your credentials in your document. Record any other important looking data points that your service has provided.
Parabola will use three URLs that are provided by your service to connect and stay connected via OAuth. The URLs are:
- A URL to display as a webpage to you so that you can authorize this connection. Many times called the authorization URL.
- A URL for Parabola to use to fetch your authorization token after you have confirmed that you would like the connection to exist. Many times the name of this URL involves the word token, like a token URL.
- A URL for Parabola to use to refresh your authorization token. Tokens typically expire in an hour, so Parabola needs a way to refresh it. This URL is sometimes the same as the token URL, or it is called the refresh URL.
Your service may lay out its documentation for connecting to it via OAuth in a similar order as the above URLs. There are generally 3 or 4 steps to OAuth, each one using a different URL. First the authorization URL, then the token URL, then the refresh URL.
Once you find the URLs, record them in your document. Don't you love a good document?
When Parabola uses each URL, it will need some additional information to pass along to identify you to the service. This is where you will be using those credentials that you gathered in step 1.
The Authorization URL
The authorization URL may require you to send along one or two
parameters to help identify who you are. Things like your
client_id and other things may be required. This information in Parabola needs to be added to the URL itself like this:
If you don't want to create that URL yourself, then just use the
key:value pairs section below the URL to add on any parameters. The two sections stay in sync with each other!
Also note that spaces are not valid in a URL. If you have spaces to send, replace them with a
plus sign + or with
Record in your document your fully formed Authorization URL, or your URL plus its parameters.
The Token URL
The token URL will specify which method or verb or request type to use to send the request. This is either a
POST or a
GET. Most likely, it is a
POST. If it is a
GET, then you need to send the required parameters in the URL and not in the body, using the same method as we used for the authorization URL.
The following assumes that your URL requires a
POST request to send the required data to your service from Parabola to get the access token.
POST requests are allowed to send something called a body in the request. This body will be sent by Parabola as JSON formatted text, in a way called
x-www-form-urlencoded, which is standard.
All you need to do is find the
key:value pairs for the body - usually a redirect_uri and your credentials, as well as a
grant_type, or something along those lines.
The documentation of your service will tell you which values in the body parameters are optional and which are not. Usually there is no need to send the optional parameters, but that is something to check case-by-case.
Some values will be required to send, but you will not have them. Most of the time, there will be a field called or dealing with a
code, which is required. That field and value will be inserted by Parabola, so don't worry about it!
The Refresh URL
The Refresh URL may be quite similar to the Token URL. In essence, its function is very similar. Instead of requesting a token, it requests a refresh.
The rules and tips from the token URL all apply to the refresh URL. The main difference is that your
grant_type parameter in the body will probably be different and indicate that this is a refresh token.
You will need to start with an API Import on your canvas.
Double click the step to view its settings, and in the Authorization setting, select
OAuth 2.0. A button should appear that says
Authorize - click it.
The following form should show up:
The form should correspond to the data that you've collected.
The 3 URLs and their accompanying body data or parameters go into the 3 sections of the form.
Once all of your form data looks correct and you are feeling lucky, click that big blue button at the bottom of the form.
When you do this, a new window should pop open showing what service Parabola is trying to connect to, and that service will ask you to log in. This log in information is entered on a window controlled by the service, and Parabola has no way of accessing that information.
If you are blocking pop-ups from Parabola, this may not work, so make sure those are allowed (this is normal).
Once you authorize Parabola to access data in the service, you will be returned to your flow and see that it is ready for use.
You have now set up the authentication, but you still need to put a URL in the URL slot and any other headers to actually make the request to the service for data.
If this did not work, you will see an error in the pop up window showing you what went wrong. Sometimes errors are from Parabola, or from the service, and range from very helpful to very cryptic. If you get an error, and are confused, reach out to us on chat!
If you hit an error during the authorization process, you can go back and edit your setting to try again. To re-access the form, click
Edit accounts at the top of the result view, then click
edit. Find the Auth that you just made, and click the pencil icon next to it to launch your saved form.
Note that from this view, you can edit the name of the auth as well!
Updated 28 days ago