Authentication

AzoraOne APIs support API keys for server-to-server interactions between your web application and an AzoraOne API. In order to gain access to API keys you need a client account, which is an account that belongs to your application instead of to an individual end user. Your application calls AzoraOne APIs on behalf of the client account, interactions do not require involvement of your end user (i.e. user action or consent).

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

How to register for a client account

To apply for a client account, contact the AzoraOne API team on support@arkimera.se. Describe why you want to register a client account and add some basic information about your company. We have no strict application policies at the time, a creative and well-motivated application may very well do the trick.

If selected, you will:

  • Receive a client key: The client key will allow you to browse available products in the developer portal. The client key is always the same and is not dependent on which products you eventually will subscribe to. The client key is application-specific, all developers belonging to your client application share the same client key.

  • Be able to subscribe to a product: As a registered developer connected to a client account, you are able to subscribe to one or more of our products. Your client key will be preassigned to every single operation in the API Explorer for all products you eventually subscribe to.

  • Receive a product-specific personal API key: Upon subscription to a product, you will get access to a subscription key. A subscription key is a unique identifier that you generate using the console. This key has full access to all resources in the APIs of the product. You can find your subscription key on your profile in the developer portal.

Your subscription key (or keys) in combination with your client key give you access to one or more AzoraOne APIs.

How to use your API keys

All requests require both a valid client key and a valid subscription key in the header. Authenticate your account when using the API by including both keys in the request.

Provide your client key as the Client-Key value in the header:

Client-Key: ••••••••••••••••••••••••••••••••

Provide your subscription key as the Ocp-Apim-Subscription-Key value in the header:

Ocp-Apim-Subscription-Key: ••••••••••••••••••••••••••••••••

On your profile page you will find that you have two subscription keys (primary and secondary keys) for every product you subscribe to. The goal of the primary and secondary keys is to allow for "rolling" upgrades, if one is not working the other key can be used. This allows you to regenerate the primary key and still be able use the secondary key. After the primary is regenerated, you can follow the same scenario with the secondary key to regenerate that.

The other scenario is for granting temporary access, you grant the secondary key to another party, and regenerate the key to revoke their access.

How to level up security in production environment

When you step into production mode, you can enhance security further by IP address restrictions. IP restrictions provide an additional security option that can be used in combination with your API keys. IP address restrictions are used to restrict access based on the IP address of your server. By white-listing only a few trusted IP addresses, all other IP addresses will be blocked from accessing your AzoraOne API services.

You can choose a specific IP address or a range if you have multiple servers that should have access to your AzoraOne API services. Only those individual addresses, or address ranges, explicitly specified by you will be allowed to make HTTP requests to your AzoraOne API services. If you want to implement IP address restrictions, contact the AzoraOne API team.

How to keep your API keys secure

Your API keys carry many privileges, so be sure to keep them secret. Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth. Publicly exposing your credentials can result in your account being compromised, which could lead to unexpected charges on your account.

To keep your API keys secure, follow these best practices:

  • Do not embed API keys directly in code: API keys that are embedded in code can be accidentally exposed to the public. Instead of embedding your API keys in your applications, store them in environment variables or in files outside of your application's source tree.

  • Do not store API keys in files inside your application's source tree: If you store API keys in files, keep the files outside your application's source tree to help ensure your keys do not end up in your source code control system. This is particularly important if you use a public source code management system such as GitHub.

  • Use your API keys only where needed: By restricting the IP addresses, referrer URLs and mobile apps that can use each key, you can reduce the impact of a compromised API key.

  • Delete unneeded API keys: To minimize your exposure to attack, delete any API keys that you no longer need.

  • Regenerate your API keys periodically: You can regenerate your subscription keys from your profile page by clicking Regenerate for each key. By using either the primary or secondary key, you can regenerate the other key and replace it in your code.

  • Review your code before publicly releasing it: Ensure that your code does not contain API keys or any other private information before you make your code publicly available.

AzoraOne is a product developed by Arkimera Robotics.