One of the most common concerns we encounter is how to protect your Aeris API credentials. While it can be difficult to have API credentials that are completely secure, we do provide tools to help assist with many threats. One of those tools is the namespace feature that we have built into the members area ready for you to use today.
Let’s start by logging into your account from the home page. Next, click on the Apps tab where you will have all the tools necessary for managing your applications. Here you will be able to add, edit, and delete applications as needed. There’s also a nifty copy-to-clipboard button for both the client ID and client secret.
There are a number of reasons why you would want to use this feature, but the first one that comes to mind is security. Most of the time your credentials can be viewed by anyone who knows how to use the developer tools within a browser – don’t worry, that’s okay! What’s not okay is when they take these credentials and attempt to use them for their own applications. In return, this would increase your usage and potentially hit your daily limit which can shut off your service until the next day. By utilizing the namespace field you are telling our system exactly who can and can’t use your credentials. When an unauthorized application requests data with your credentials, we reject the request and throw an HTTP 403 error. There’s even a JSON error response for this specific occasion:
"message": "The request was made from outside the allowed namespace for the client."
Another great reason to use the namespace feature is because we provide metrics based on each individual application you have registered. Under the Usage tab we break down each individual apps usage for you over various time frames. This will help you isolate each application and understand how the data is being distributed.
I’ll use this section to outline the steps that go into adding, editing, and deleting applications.
After you’ve created your Aeris account, log into the members area and navigate to the Apps tab. You should already have one application titled Demo with the wildard character (*) as your namespace.
Let’s start by updating the title and namespace to something more suitable. Hit the edit icon on the right side of the screen and you will be prompted with an overlay. I’ll change the Application Name to iOS App and, more importantly, update the namespace field to ‘com.aerisweather.myweatherapp’. Hit Save App and now only requests from this namespace will be allowed to use this ID / Secret combination. When updating existing applications, it may take up to 30 minutes for the changes to take affect as our caching system updates.
Congratulations, you have successfully updated your first application!
Start by clicking the New Application button in the top right corner of the Apps page. You have been prompted with a similar screen from the last example where you will enter an app name and namespace. This time I will enter my Android app information and hit Save App.
Each application you create will have a new client secret. Your client ID will remain the same for all apps, but in order for us to provide metrics at the app level we create a new client secret each time you add an app. This also means one set of credentials may not work with your other applications depending on how you have your namespaces setup.
Let’s say you are terminating an app and no longer need the id/secret combination associated with this application. You can delete your app by hitting the Trash icon associated with that particular app. You will then be prompted with an “Are you sure?” overlay prior to confirming. PLEASE BE SURE BEFORE DELETING YOUR APP! Excuse the caps, but I cannot stress this enough. Once you delete your application there is no way to recover the id/secret combination.
A couple useful tips I thought I would cover before letting you go:
Wildcards can come in handy if you have multiple subdomains. For example, let’s say we want to put a map on www.aerisweather.com and wx.aerisweather.com. You don’t need to create multiple applications for both sites (you can if you want) so you can put an asterisk in place of the subdomain like so:
Say you have a couple different websites with different domains, but you don’t want these applications to be separate. We give you the ability to add multiple domains for a single application by simply adding a comma between each domain. Here’s an example:
Now both www.aerisweather.com and www.noaa.gov can utilize the same API credentials. Please be sure to not include carriage returns in between domains as this will not work.
We do not limit the number of applications you can add to your account. We allow this because your usage limits are based on the all applications combined. So feel free to create applications for all of your dev, staging, and production environments – the possibilities are endless!
If you believe your API credentials have been compromised, first try editing the namespace for that particular application. If that doesn’t help, the quickest solution is to delete the existing application and create a new one. You will also need to update the app that is using these API credentials. If you believe you are still experiencing unauthorized usage with your API credentials, please contact our support staff.
When you update your existing applications please note this can take up to 30 minutes before the results are seen. However, new applications are ready to roll as soon as they are created.
Now that you are familiar with the namespace feature it is time for you to start developing new applications with ease of mind that nobody is stealing your access. Don’t have an Aeris account yet? Have no fear, a free developer account is waiting for you here!