Overview

This guide shows you how to update your app or integration to adopt the changes for the Ansira API Gateway 2.0 and its corresponding REST APIs. It describes how authorization improvements affect the REST APIs, provides a migration path to the new REST APIs, and lists all of the REST API changes.

Deprecation Notice

In 2012, we released version 1.0 of the Ansira API Gateway, and on August 22nd, 2022, we announced that v1.0 will be sunset on April 3rd, 2023. On this date, all requests made against v1.0 of the REST API will fail. This guide explains how to update your application for compatibility with v2.0. We recommend migrating as soon as possible to ensure your application is unaffected.

Migration Guide

The Ansira API Gateway 2.0 is a complete revamp over the current API Gateway 1.0, which is more secure, easier to integrate, lighter, slimmer, faster, and offers features consistent with industry standards and best practices for serving RESTful services.
This guide will help you migrate your existing application integrating with the API Gateway 1.0 to the API Gateway 2.0.

What's New In Ansira API Gateway 2.0?

On a high level, the Ansira API Gateway 2.0 offers the following new features:

• Access authorization based on OAuth 2.0. It allows a user to grant a third-party website or application access to the user's protected resources without necessarily revealing their long-term credentials or even their identity.
• OpenAPI 3.1 compatibility. It improves discoverability and understanding of the service capabilities without access to source code, documentation, or through network traffic inspection
• JSON-based content. It supports the lighter and slimmer JSON format over XML supported earlier.
• Faster response times. The new API Gateway has been redesigned to offer faster response times. 
• Improved response codes and more graceful error handling based on RESTful API best practices.

Who Is Impacted?

Brands actively making requests to the following API Gateway 1.0 API URLs:

• api.sproutloud.com/profiles
• api.sproutloud.com/funds
• api.sproutloud.com/tp_attributes
• api.sproutloud.com/membersso
• api.sproutloud.com/mastersso

IMPORTANT: The following integrations are not affected:

• SAML 2 SSO: This service doesn’t rely on OAuth 2.0 and will remain untouched.
• api.sproutloud.com/lists: Brands using our legacy List API will receive an extended access time to the API Gateway 1.0 until the newer List Management API is available.

Migration Checklist

The following flow describes the API Gateway 1.0 → API Gateway 2.0 Migration Checklist on a high level:

1. Identify the changes and define the migration plan
2. Identify and review the REST-API documentation
3. Register a new API client
4. Update and test your app integration with the API Gateway 2.0
5. Deploy and run your integration in production

The following topics contain more details on each of the steps mentioned above.

Step 1: Identify the Changes and Define the Migration Plan

In addition to updating the URLs for your REST-API calls, you also need to update your app integration to account for some breaking changes introduced in the API Gateway 2.0.
There are two main differences between API Gateway 1.0 and API Gateway 2.0:

• Authorization mechanism. The API Gateway 2.0 uses OAuth 2.0 to authorize access to endpoints in the REST-API.
• Content negotiation. The API Gateway 2.0 supports only JSON format for requests and responses.

Because of these differences, you should expect changes in the request/response structure of the REST-APIs. Please refer to this document’s section Authorization and REST-API Changes for more details.

Step 2: Identify and review the REST-API Documentation

A REST-API documentation is an OpenAPI 3.1 document using an open-source format for describing and documenting APIs. You may find more information about the OpenAPI Specification and how to use them at https://swagger.io/docs/specification/about/

Before you start integrating with the API Gateway 2.0, it’s recommended that you check the REST-API specifications from the Developer Portal menu → APIs.

Step 3: Register a New API Client

Your existing credentials (API Access Token) won't work with the API Gateway 2.0, so you must register a new API Client before making any requests to one of Ansira’s REST-APIs. To create your first API Clients, you can refer to our Getting Started article.

IMPORTANT: Ansira recommends registering a single client per application or integration and giving the client only the required scopes. In this way, the contact surface is limited and security improved.

Step 4: Update & Test Your App Integration

Using the list of identified changes in the request or response structure, you can adjust your app integration accordingly. We recommend using our STAGE environment to test your integration. If you encounter issues while testing your updates, you can contact your CRM team..

Ansira does not provide out-of-the-box client libraries for different coding languages. However, you may use tools such as Swagger CodeGen, which allows the automatic generation of API client libraries (SDK generation), server stubs, and documentation, given an OpenAPI Spec.

Step 5: Deploy & Run Your App Integration in Production

To deploy your app integration in production you require an API Client in our PROD environment authorized to access the REST-API endpoints used by your integration. You can create a new API Client following the same process described in Step 1.

IMPORTANT: Regardless if you created a new client or updated an existing one, make sure you update the credentials in your app integration.

Authorization

Your app integration must use OAuth 2.0 to authorize requests. No other authorization protocols are supported. Every request your app integration sends to the API Gateway 2.0 must include a user assertion or authorization token.

Authorization flows

The API Gateway 2.0 supports two OAuth 2.0 authorization flows:

• Assertion Flow
• Manual Token

Assertion Flow

The OAuth Assertion Framework [RFC7521], or Assertion Flow, defines a generic framework for the use of assertions with OAuth 2.0 in the form of a new client authentication mechanism and a new authorization grant type.
A user assertion is a user token that contains identity information about the user. The user assertion can be used directly as an authorization grant to obtain an access token.

This flow has significantly different security properties than the other OAuth workflows. The primary difference is that the user’s credentials are never accessible to the application.
This is how the assertion grant works:

1. The client obtains an assertion from our Developer Portal. This can be done during the registration of a new client or at a later time.
2. The client uses the assertion to make an HTTP request to the token endpoint in Ansira's Identity Server (IdS) to exchange the assertion for an access token. 
3. The IdS validates the assertion and returns an access token. 
4. The client uses the token to obtain data in an API call to the API Gateway 2.0. The access token is included as the HTTP authorization header for each request using the authentication type bearer.

The assertion grant is more secure than the resource owner password credentials grant, or the client credentials grant because the user’s credentials are never exposed. Because of this, the assertion grant is the preferred authorization flow.

Manual Token

Some clients may not be able to use the Assertion Flow because they have limited capabilities and may support only setting a token or API key as authorization header. Clients that do not support the assertion grant flow can use the Manual Token flow or 2-Legged OAuth Grant.

The Manual Token flow uses a token to validate permissions and the identity associated with the entity requesting the operation. This is how the 2-Legged OAuth grant works:

1. The client obtains an access token from our Developer Portal. This can be done during the registration of a new client or at a later time.
2. The client uses the token to obtain data in an API call to the API Gateway 2.0. The access token is included as the HTTP authorization header for each request using authorization type bearer.

In this scenario, a client can obtain an access token directly from the Developer Portal and use it on a later request. Before implementing this authorization flow in your app integration, you should consider the following limitations:

• The tokens have a shorter time to live (TTL) than assertions. The TTL of a token depends on the value set during the registration of a client. The maximum supported TTL is 86400 minutes (60 days). 
• Refreshing an access token is not supported. Your app integration will not be able to extend the TTL of a token. Once a token has expired, you would have to obtain a new token from the Developer Portal.

REST-API Changes

To update your application or integration, read the list of REST API changes in this section. The changes are listed by resource and include instructions on what you need to update.

We recommend migrating to the latest version of our APIs, but if you have limited development resources and can’t deliver this transition by the sunset date, we also offer, in some cases Transition APIs.

Transition APIs offer similar content negotiation as the API Gateway 1.0. These APIs are JSON formatted so the changes are limited to supporting OAuth 2.0. You may have to wrap data if you are using XML APIs.
IMPORTANT: There is no sunset date for the Transition APIs, but we encourage you to move to the latest APIs as soon as possible.

Migration Options

Notes: All migrations to the API Gateway 2.0 require upgrading the authentication to OAuth 2.0. 

Content Updates	To Latest API	To Transition API
From XML	Upgrade the content negotiation (Payload)	Wrap the content negotiation (Payload)
From JSON	Upgrade the content negotiation (Payload)	None

Migration to Latest APIs

API Gateway 1.0 URL	API Gateway 2.0 Documentation
api.sproutloud.com/profiles	/api/account_management_v1
api.sproutloud.com/funds	/api/funds_v2
api.sproutloud.com/tp_attributes	/api/account_management_v1
api.sproutloud.com/membersso	/api/authentication_v1
api.sproutloud.com/mastersso	/api/authentication_v1

Migration to Transition APIs