This guide will walk you through the process of creating a very basic client-side integration and can be used as the basis for developing simple Micro-Apps on the Allthings Platform.
In this guide, you will learn how to:
All authorization on the Allthings Platform is done with OAuth 2.0. As a developer, you'll need to create an Allthings OAuth Client in the Developer Console to gain access to APIs.
To create an OAuth Client, head over to the Developer Console. If you don't yet have an Allthings user account, you can create one when prompted to log in by following the "Sign Up" link.
Next, once logged in to the Developer Console, follow these steps to create a new OAuth Client:
Allthings allows developers to make use of three different types of OAuth Clients: Code Flow (public-client authorization-code flow), Code Flow (confidential-client authorization-code flow), and System-to-System (client-credentials flow). System-to-system clients require special permissions be granted to them. In order to use a system-to-system client in production, please contact our support team.
If you wish to perform API requests as, or on behalf of a user, you will want to create a Code Flow client. If you want to make machine-to-machine API requests, for example as part of a Webhook-based integration, you'll want to create a System-to-System client. You can find further details about OAuth and OAuth Clients in our Authorization documentation here.
For the purposes of this Quickstart guide, let's create a "Code Flow - client only" client. This type of client (a public client) is intended for applications running in a browser or on a mobile device.
Once you've created your OAuth client, you'll be presented with a screen that allows you to configure a number of fields on the OAuth Client:
With an OAuth client created, we're ready to use it. In the next section we'll create a simple integration.
Our simple integration will be, well, very simple. We will ask a user to authorize our integration so that we can perform API requests as, or on behalf of that user. Then, in our simple web application we will display a welcome message with the user's name. That's it. While simple, this is the basis on which you'll be able to build further features simply by making further API requests or integrating with your own APIs. Let's get started.
You can jump to the complete example source code here. You can also run the completed example in your browser here. Just make sure to update the clientId with your OAuth Client ID and update your OAuth Client with your Redirect URL.
We'll use CodeSandbox in this guide as it allows us to build this whole integration without ever needing to install anything locally on your computer or to run your own serverβand it doesn't require any signup.
Let's create a new sandbox. Open up this link in a new browser tab or window. You'll be presented with a small code editor on the left of your screen, and a preview on the right.
Delete all of the text in the index.html file the editor window. Next, copy the following code and paste it into index.html.
This markup code lays down some scaffolding. Of interest is line 5. There we load the Allthings Javascript SDK. The SDK will do most of the heavy lifting for us including abstracting away most of the complexity of the OAuth authorization flow.
Having pasted the above code into CodeSandbox and saving your changes to index.html, you should see something like this:
Next, replace the text // we'll add code here.
with the following code:
The above code is all you will need to make authorization with OAuth work.
In the code you just pasted, we need to replace π Put your OAuth Client ID here
with your Oauth Client's Client ID. You can find your OAuth Client's Client ID back in the Developer Console where you previously created your OAuth Client.
Next, we need to configure the RedirectUri in your OAuth Client. Again, in the Developer Console, on the same screen you've copied the Client ID from, we need to add a new redirect URI. Add your CodeSandbox's preview URL as a new redirect URI to your OAuth Client. You'll find your CodeSandbox's preview URL in the left preview pane.
When adding a redirect URI, make sure to click the "add" button, then "save".
Also make sure that you've also provided either a Terms of Use or Privacy Policy link (or both) on the OAuth Client. Without one of these, you won't be able to authorize users.
With all that setup, let's add the final piece of code. Replace the line // We'll make an API request here.
with the following code:
These few lines will fetch information about the currently logged in user from the Allthings API and display it in the page. We make use of the Javascript SDKs client.getCurrentUser()
method to do all of the work for us.
Now, make sure to save your changes to index.html in CodeSandbox.
Finally, we can test our simple integration. Open the preview URL you copied earlier (the redirectUri) in a new browser tab or window. If everything was set up correctly, you will be redirected to the Allthings ID account service and prompted to authorize your integration (OAuth Client). Once you've granted authorization, you'll be redirected to your redirectUri, in this case, your CodeSandbox URL where you'll be greeted with a welcome message, Hi there, {{username}}. You're logged in!
π That's it! You've just completed your first Allthings integration!