Authentication & Authorization

The API is secured to ensure that only authorized users can access the endpoints they have been provisioned to access. The Aspire External API uses Bearer Authentication to provide a subscription-based security method using a  bearer token. To use the API, you must generate a Client ID and Key  to obtain an access token.  

Requirements 

Authentication requires: 

•  An Aspire user account with Admin permissions to log in to Aspire. 
• Once logged in, API credentials need to be created for authentication. 
• Create an access token via the POST/Authorization endpoint using the API credentials (Client ID and Secret). This token will then authorize access to endpoints available to the logged-in user. 

Authenticate

An admin user within the Aspire desktop application must create credentials for the API user by following these steps: 

1. Go to the Aspire application and select Administration > Application > API > New. 

2. Create a Description that appropriately describes the user or the specified purpose for the set of credentials. 
3. Copy the Client ID and Secret and store it where you can retrieve it later.
   IMPORTANT: Losing your Client ID and Secret will require you to regenerate a new one and update any integration currently using the previous credentials. 
4. Select the endpoints that you want to provide access to under the Scope section. 
5. Select Save. 

Authorize

Use authentication credentials to generate an access token (JWT) to be placed in the header of all requests.

API Guide Authorization

Use the following steps to create an access token from the API Guide: 

1. Go to the POST/Authorization endpoint.
2. Enter the ClientId and Secret and click Try It!
   Since the "Token" under the "Authentication" section of the interactive console is required, enter "123" in this field. The only purpose of this workaround is to enable the "Try It" button after entering your credentials. It can not be used to authorize the use of endpoints. You will use the Token generated in the "Body" of the interactive console for authorization. 

   
   
3.  With a success (200) status code, you should see the value of the token and refresh the token in the response body. Copy the entire token string. 
   1. Do not copy the RefreshToken string or the quotations. Copy the  RefreshToken separately and paste it somewhere secure so you will have it to refresh the token later.
   2. Ensure quotes are enclosed.

4.   Copy the token value, select an endpoint to interact with, and enter the value in the Token field under Authentication for the endpoint you have selected. 

1. After entering information within the query or body parameters of the endpoint selected, click Try It to commit the changes. Once submitted, the token will automatically populate under all available endpoints you interact with until the token expires. 
   

Swagger UI Authorization 

Use the following steps to create an access token using the Swagger UI. 

1. Go to the Swagger UI  tool.  
2. Expand the POST/Authorization endpoint and select Try It Out. 
3. Enter the ClientId and Secret > Execute. 
   1. Ensure quotes are enclosed. 

4.  With a success status code, you should see the token's value and refresh the token in the response body. Copy the entire Token string. 
   1. Do not copy the RefreshToken string or the quotations. Copy this section separately and paste it somewhere secure to use the string to refresh the token later.

5. Select Authorize in the top right corner of the screen, paste the copied Token value in the Bearer Authorization Token Value field, and select Authorize. 

1. The padlock icon within the SwaggerUI will appear locked once the token is saved. 

Refresh Token 

Use this token value with the POST/Authorization/RefreshToken endpoint to refresh usage for another 24 hours before the expiration of your token. 

Token Expiration 

The token expires every 24 hours on a rolling basis. Meaning that the 24 hour timeframe resets every time you interact with the API.