Getting Started with APIs

Getting Started with APIs

by admin | Thu, 01/13/2022 - 17:02

Getting Started

Welcome to Ansira’s Developer Portal - your resource for all available APIs within the Ansira platform. 
Every API comes with documentation listing its endpoints, methods, scopes, requests, and responses.
Our APIs use OAuth 2.0 as the standard protocol for authorization. You can read more about OAuth 2.0 here.


To get started

  • Review our API Documentation from the Developer Portal menu -> APIs (Certain documentation require to be logged in).
  • Identify the APIs required for your integrations.
  • Create the API Clients with the scopes required for your integrations. To do this, you must be logged in.
  • Determine the authorization methods. 


Notes:

  • Our legacy XML and REST JSON APIs will remain available in the Developer Center until April 3rd, 2023.

Creating a New API Client

To limit the contact surface and increase security, Ansira recommends creating one Client per integration. The following information is needed to create a new API client:

  • Client Name: A user-friendly name that allows you to organize, identify, and search your API Clients easily.
  • Client Identifier: A  system-generated unique identifier used during the Assertion Flow.
  • Client Secret: The Password used during the Assertion Flow.  You can let the Ansira system generate a secret for you or input your own. Important: For security reasons, the secret is only displayed when setting up an API client and will not be displayed afterward. However, you can generate or input a new secret as needed.
  • Scopes: The individual permissions that are required for an integration. The list of scopes required for an integration can be found under the API menu.
    Note: While the entire set of APIs and scopes are displayed in the Specifications section, only the scopes of the modules assigned to your account are available.
  • Assertion Expiration Date: You will be able to use this API Client to generate assertions and tokens until midnight of the selected date of the API Client timezone. Ansira recommends using a date two years in the future to prevent frequent maintenance windows unless your security standards suggest otherwise.
  • Access Token Time to Live: The time in minutes that the Access Token can be used to perform API calls. Ansira recommends setting this time to 5 minutes. Tokens can be used multiple times until they expire.
  • Email Reminders: To help you plan for your maintenance windows, the Developer Portal can send you email reminders before the Assertion expires. We recommend using group email to ensure maximum reach.

Create New API Client

Authorization and Access Token Management

Each API call is authenticated and permissioned by Access Tokens that are generated for each API Client. Ansira supports two methods to generate Access Tokens:

  • Assertion Flow: This method allows for generating tokens in an automated manner. Ansira recommends using Assertion Flow for production systems whenever possible.
  • Manual Token: Access Tokens can be obtained directly from the Developer Portal.
    Ansira recommends this method only for development, testing purposes, and systems that don’t support Assertion Flow.

IMPORTANT:

  • Access Tokens honor the TTL defined during the creation of their associated API Client.  The TTL countdown starts when the Access Token is created, not on first use. 
  • Multiple Access Tokens with overlapping TTLs can be generated and will remain valid until they expire or are explicitly invalidated (See this document Access Token Invalidation).
  • Access Tokens can be generated as long as the Client Assertion has not expired.

 

Assertion Flow

Assertion generation

This flow has significantly different security properties than the other OAuth 2.0 workflows. The primary difference is that the user’s credentials are never accessible to the application.
The Assertion Flow requires the generation and download of an Assertion. Generating and downloading a new Assertion will invalidate any Access Tokens previously generated for that API Client. See the Access Token Invalidation section of this documentation for more information.

Assertions can be generated and downloaded until the Assertion Expiration date. If the Expiration Date is passed, you will have to set a new Expiration Date by editing the API Client before generating a new Assertion.

Token Generation

A request must be made to the Ansira Authentication Server to generate Access Tokens from an Assertion.

Request Header

  • URL:
    • Stage: https://auth-stage.sproutloud.com/oauth/v2/oauth-token
    • Production: https://auth.sproutloud.com/oauth/v2/oauth-token
  • Method: POST
  • Authorization: Basic <A base64 of the “<Client Identifier>:<Client Secret>” string>
  • Cache-Control: no-cache
  • Content-Type: application/x-www-form-urlencoded
  • Content-Length: <The string length of the request body. This is usually calculated by the software performing the API call>
  • Host: <Same host as the URL. E.g., auth.sproutloud.com>
  • Accept: application/json
     

Request Body

  • grant_type: urn:ietf:params:oauth:grant-type:jwt-bearer
  • scope: <The list of scopes the client is setup with>
  • assertion: <The content of the assertion file downloaded from the API Client Management page>
     

Response Body

Successfully calling the Assertion Flow will return a 200 (OK) response code with the following JSON content:

  • token_type: bearer
  • access_token: <The value of the access token to be used when performing an API call (the Authorization attribute)>
  • scope: <A comma-separated list of scopes this token is authorized for>
  • claims: <List of data-points used by Ansira for internal authentication>
  • expires_in: <The remaining TTL for the Access Token expressed in seconds>

 Manual Token

New Access Tokens can be generated manually from the user interface. Manually generated  Access Tokens are delivered as file downloads to your computer.

 

Invalidating Access Tokens

For security purposes, Access Tokens can be invalidated either automatically by the Ansira application or manually by you. Performing an API call using an invalidated Access Token will result in an error. See the Errors section of this documentation.

Manual Invalidation

If you need to invalidate Access Tokens previously generated for an API Client, you can either generate a new Assertion or delete the API Client.

Automatic Invalidation

Tokens are automatically invalidated when they expire.  Tokens are also invalidated anytime you update the list of scopes for the API Client.

Performing an API call

Request Header

  • URL: <The API endpoint to be called based on the Specifications. This parameter must be URL encoded.>
  • Method: <The access method to be called based on the Specifications. E.g., GET., POST, ...>
  • Authorization: Bearer <access_token> (retrieved from calling the Assertion Flow or the Manual Generation)
  • Cache-Control: no-cache
  • Host: <Same host as the URL. E.g., api.sproutloud.com>

Filtering, Sorting, and Pagination

Most endpoints offering listing functionalities also provide filtering, sorting, and pagination.
Filtering: Filtering can be achieved through the filter parameter; this parameter should be used to narrow down the number of records returned in the resulting collection based on your specifications. Multiple filters can be concatenated using Boolean operators. Example: filter=<filter_condition><boolean_operator><filter_condition>

Sorting: Collections can be sorted through the use of the order_by parameter. This parameter specifies the order in which the records are returned. It is also possible to specify multiple fields to sort against: order_by=<sort_expression><sort_expression>

Pagination: The pagination allows the management of which page is returned and the size of the page: page=<page_number>&page_size=<page_size>
 

Response Body

Successfully calling an API endpoint will return a 200 (OK) response code with the JSON content described in the API's Specifications.

Errors

  • 401 (Unauthorized): The Access Token is missing. Enter the required value in the <Authorization> field when performing the API call.
  • 403 (Forbidden): The Access Token could be expired, or it was not granted the scopes required for that endpoint. Generate a new Access Token from an Assertion offering the correct Scopes.
  • 404 (Not Found): The resource doesn’t exist. Review the Specifications and perform the API call to the correct URL.
  • 429 (Too Many Requests): Your servers passed the max Rate Limit per IP address for the endpoint (Stage: 5 per second, Production: 10 per second). Some endpoints have a Rate Limit override that is defined in their Specifications. Lower the number of calls coming from that IP address.
  • 500 (Internal Server Error): Ansira’s system encountered an issue while processing your request. Please contact Ansira Support.
  • 503 (Service Unavailable): Ansira’s system received too many calls for this endpoint. Implement an exponential backoff to retry the call later.
  • 504 (Gateway Timeout): If an API call takes more than 30 seconds, you will receive this error. Please contact Ansira Support.
  • Other specific error codes may be defined in each API's specifications.