Insomnia Blog

Welcome, sit back and take a rest with our latest articles.

Announcing Insomnia 2021.1

TL;DR Insomnia Designer and Insomnia Core are now Insomnia. Insomnia Designer users will have to migrate to the new Insomnia application and Designer will no longer receive updates. When we originally built Insomnia Designer, we didn't want to make large changes to Insomnia without understanding whether the changes would be useful to developers, with the release of Insomnia Designer we were praised for not making these changes directly inside of Insomnia at first. However, over the course of the year through user feedback and observation was users moving away from Insomnia Core, to Designer some of its features and enhancements such as the Dashboard, Git Sync, and Unit Testing capabilities. Based on this user feedback, observations and internal discussions, we've merged Insomnia Designer and Insomnia Core. What does this mean for Insomnia Core? Users of Insomnia Core will automatically get the new update through the auto-update release channel, or can download the new update directly from the Downloads page or the Github releases page. For existing users, there are a few notable changes: Dashboard for managing request collections (previously known as workspaces) Sync menu has been moved to the top right of the header Sync pull menu has been moved to the dashboard next to create menu For a complete list of changes see the changelog. What does this mean for Insomnia Designer? All functionality of Insomnia Designer is now available in the latest single release of Insomnia. Insomnia Designer users upon download of the latest version will be prompted to migrate data, plugins and settings. Moving forward the Insomnia Designer application will no longer receive updates. For a complete list of changes see the changelog. What can we expect in the future? I want to end this post by stating directly that this does not mean design is less of a priority, or that we won't be working on design functionality, this is exactly the opposite. It's now a core part of what Insomnia is. This release is just the start of the features and functionality that comes from this merge: Adding ability to group request collections and design documents in the dashboard Adding ability to use unit testing for request collections Adding plugin APIs for dashboard and design functionality Adding git sync support for request collections Adding ability to automatically generate specifications from request collections Improved theming support for the dashboard and design functionality. and more‚Ķ Last but not least ūü§ó A huge shout out to everyone who worked on this release, and came together to get it out of the door. Not only that but everyone who submitted PRs who didn't make the cut this release but will be in the next few releases as well.

Written by
Nijiko Yonskai
Published on
2021-03-04
Tags
Release

GitHub API Authentication using OAuth 2.0

OAuth 2.0 has been a supported authentication scheme in Insomnia for some time now but ‚Äď if you are new to OAuth ‚Äď can still be quite complicated. This post walks through an example using OAuth 2.0 to authenticate and create a repository on GitHub using the¬†GitHub API. If you don't already have a GitHub OAuth application registered for your account, you can create a one from¬†Developer Settings¬†Note, "Callback URL" can be whatever you want for this tutorial. Gathering OAuth Credentials The GitHub API uses the OAuth¬†Authorization Code¬†grant type, which requires five things from you. Note that you don't need to know what a¬†grant type¬†is to follow along. Client ID,¬†Client Secret, and¬†Callback URL: These are specific to the GitHub OAuth application and can be found on its¬†details page. The¬†Callback URL¬†is often optional but we're going to specify it anyway in the name of completeness. Authorization URL¬†and¬†Access Token URL: These are static values, listed on the¬†GitHub API Docs. As a convenience, Insomnia will autocomplete these while you type them and I will also include them here: http://github.com/login/oauth/authorize https://github.com/login/oauth/access_token This following step is optional, but I recommend specifying the application-specific values as¬†Environment Variables¬†so they can easily be reused or modified. For my setup, I have created a sub environment called "Test Application" and included the following JSON value: { "client_id": "fa122270cdf09954296d", "client_secret": "274e6d43420c73d9c89f52a4a99a9731e6bdb96c", "redirect_url": "https://insomnia.rest" } Don't forget to activate your new environment in the sidebar after creating it Now that we have everything we need, let's start setting up a request. Setting Up The Request Most read-only endpoints on GitHub don't require authentication (not very useful for demoing OAuth) so we'll be using the¬†create repository¬†endpoint for this demonstration. To get started, open Insomnia and create a new request by the name of "Create Repository". Then, copy and paste the following curl command into the URL bar. We're making use of Insomnia's¬†import from Curl¬†feature here to save on typing. curl --request POST \ --url 'https://api.github.com/user/repos' \ --header 'content-type: application/json' \ --data '{ "name": "insomnia-test-repo", "description": "Test repo for Insomnia tutorial" }' You should end up with a request that looks like this. Setting up OAuth 2.0 If you sent the request now, before setting up authentication, you would receive a¬†401 Unauthorized¬†response. This is because the¬†POST /user/repos¬†endpoint requires an OAuth token to be sent with the request. However, obtaining an OAuth token manually is not easy and requires multiple, complicated steps. This is where Insomnia into play. Insomnia deals with the complex task of obtaining and managing OAuth tokens so you don't have to. You don't even need to understand how it works ‚Äď although I still recommend you learn. ūüĎ©‚ÄćūüíĽ Now, back to the request. Select the Auth tab of your "Create Repository" request and change the authentication type to "OAuth 2". After doing that, fill out the values you collected earlier. If you made use of environment variables, it should look something like this. Congratulations! The request is now ready to be sent. ūüėĄūüĎŹūü§Ė Sending the Request Submitting the following request will create a new repository on your GitHub account. You can delete the respository from the GitHub website later. As soon as you send the request, Insomnia will detect that a token has not yet been obtained and start the authentication process. You will be prompted to sign in with your GitHub credentials and authorize the OAuth application to act on your behalf. After logging in, the token will be extracted from the resulting URL and stored in Insomnia. The request will then be sent using the newly acquired token. If all went well you should see a successful¬†201 Created¬†response with information about your newly created repository. Make use of Insomnia's response filtering by entering a JSONPath query such as¬†$.owner.login¬†below the response body More About OAuth 2.0 Even though Insomnia handles most of the complexities of OAuth for you, there are a few notable things that may come in handy. Viewing the Authorization Header If you take a look at the Timeline tab, you will see the¬†Authorization¬†header that was sent with the request. The value of the header¬†Bearer <TOKEN>¬†contains the token that Insomnia extracted during the login process. This token will also appear in the Auth tab of the request, where you can either refetch a new token or clear the existing one. Expiring Tokens and Refresh Tokens Some OAuth 2.0 APIs make use of expiring tokens and/or refresh tokens. If the API token received has an expiry, Insomnia will show it at the bottom of the Auth tab. If a token expires, Insomnia will automatically try to refresh it when the next request. You can also trigger a refresh manually from the Auth tab. Other Grant Types OAuth 2.0 defines four¬†grant types¬†that can be used to fetch a token, each to facilitate different use cases. Authorization Code Implicit Resource Owner Password Credentials Client Credentials Insomnia supports all of these grant types and will take care of all the complexities so you don't have to. OAuth 2.0 has the ability for custom grant types, but these are not yet supported Login Window Cookies Currently, the OAuth 2.0 login window uses a single global session that is cleared on every restart of the app. That means, if you already signed in with one GitHub account, it won't need ask you again. However, this also means that, if you want to switch GitHub accounts, you will need to restart the app to clear the current session. Wrap-Up There have been a significant number of users asking for help with the OAuth 2.0 process. Hopefully this post was able to clear up some of the more common issues around the OAuth process. Even if you are not interacting with the GitHub API specifically, the information covered here will work for most other OAuth 2.0 APIs.

Written by
Nijiko Yonskai
Published on
2017-06-23
Tags
Guide