Authorising APIs
To make an authorise API request you need 2 things:
A Subscription Key
A Bearer Token
Each of these pieces of information comes from a different place, as described below.
Subscription Keys
Subscription Keys are a key that is generated whenever you are subscribed to a product in Developer Portal (this portal). While these keys are not 'sensitive', it is worth limiting access to them where possible. Keys are associated with your Developer Portal account, which is different from your Naus account. Your Developer Portal account is the account you use to access this service. You may have more than one product - use the subscription key for each product to call the APIs associated with that product.
Developers should have their own Developer Portal accounts for browsing the APIs, however we recommend that you also create an account with a shared mailbox that you use to subscribe to products on this site. These are the subscription keys you should use from your running software, as they will not be associated with an individual developer.
Bearer Tokens
As described below, Bearer Tokens are securely-negotiated secret tokens used to call the APIs. The Bearer Tokens you use will be associated with a Naus Service Account which will be supplied to you, which is different from your Developer Portal account. All API calls should be made using a bearer token generated as below. Any Bearer Token, and the credentials used to make one, are sensitive information.
API Access
The Naus API is a JSON over REST API, with definitions in Swagger (swagger.io). Endpoints are secured with JWT (jwt.io/introduction) Bearer Tokens.
Accessing an API assumes that you have been provided a Client account with a Client ID and Client Secret. If you do not have this, please contact support.
Using Subscriptions
To access an API, you must be subscribed to a product which gives access to that product. You can see what products you are subscribed to on the Manage screen.
A typical product will look like:
If you click 'show' on any key, you will see the Subscription Key you can use to access any API associated with that product (you can click through the product name to see the APIs for that product). This key must be set as the Ocp-Apim-Subscription-Key header on all requests.
For examples on how to call APIs with a subscription key, click the 'Try it` button when viewing any API.
Aquiring a Bearer Token
WT Tokens must be acquired from the Naus Authorization Service. While the token can be decoded and viewed with a tool such as jwt.io, the token also includes a digital signature which is used to verify that the token has not been tampered with. Bearer Tokens for Service Accounts are acquired using OAuth2 Client Credentials. The authorization server token URLs are:
To gain a token you must POST to the token endpoint a request of content type application/x-www-form-urlencoded containing your credentials. For example:
The response will be a JSON object with your Bearer Token, as well as your expiration time and refresh token.
Access an API with a Bearer Token
To use the token acquired from the Authorization API, simply add it as a Bearer token to your Authorization Header on all requests (note the space between 'Bearer' and your token):
Note: The bearer token acquired when using the 'Try it' feature of this website is not for use by calling applications. That token is acquired using 'Resource Owner' credentials and is tied to your personal account, not your provided Client account.