Account Aggregator (AA) Change Log

It summarizes the changes in the AA APIs requested by the AA ecosystem community.
You can send the suggestions/queries regarding AA APIs changes by mailing us on aa-api@rebit.org.in .

Feb 23, 2021

Summary

• POST /Consent
  1. Referred fiTypes from common model FITypes to avoid inconsistency.
  2. Added new enumeration value as USER in type field of Data Consumer element to identify whether end data consumer is FIU or Customer.
  3. Updated description of Frequency field to define maximum frequency for FI data fetch.
• GET /Consent/{id}
  1. Referred fiTypes from common model FITypes to avoid inconsistency.
  2. Added new enumeration value as USER in type field of Data Consumer element to identify whether end data consumer is FIU or Customer.
  3. Updated description of Frequency field to define maximum frequency for FI data fetch.
• POST FI/Request
  1. Updated description of params and Nonce field to standardize the secure cryptographic primitives to perform end-end encryption.
• GET /FI/Fetch/{sessionId}
  1. Updated description of params and Nonce field to standardize the secure cryptographic primitives to perform end-end encryption.
  2. Removed line format:binary from encryptedFI field of FIFetchResponse model.
• Common changes
  1. Removed line format: byte

1. POST /Consent

Below changes are done in request body ConsentRequests model.

1.1. Referred fiTypes from common model FITypes

Why was this change needed? FIType enum values were defined multiple times causing inconsistency.
What about the old fields? NA
Has any data changed? NA
What has changed in the API? Declared a common model for FIType with enum values and referred it in all occurences in API spec.
Other APIs impacted due to this change:

• GET /Consent/{id}

Summary of changes in YAML

{
fiTypes:
	$ref: '#/definitions/FITypes'
}

1.2. Added new enumeration value as USER in type field of DataConsumer element

Why was this change needed? There is a need to distinguish data consumer as USER if AA client is consuming the data from FIP instead of FIU. Also in future if a mechanism is implemented to incentivize the FIP for data, data fetch from FIU and data fetch from AA needs to be distinguished.
What about the old fields? NA
Has any data changed? Yes, a new enumeration value 'USER' is added.
What has changed in the API? Added new enumeration value as 'USER' in the DataConsumer field of ConsentDetail model.
Other APIs impacted due to this change:

• GET /Consent/{id}

Summary of changes in YAML

{
type:
type: string
description: Type of DataConsumer
enum:
	- FIU
	- AA
	- USER  //Added
example: AA
}

1.3. Updated description of Frequency field.

Why was this change needed? Currently there is no limit specified on the frequency of FI data fetch. Hence the maximum frequency is defined as 1 request per hour. Similaraly it will be 24 requests per day and so on.
What about the old fields? NA
Has any data changed? NA
What has changed in the API? Updated description of Frequency field in ConsentsRequest model. FIU needs to implement business logic as per the updated description.
Other APIs impacted due to this change:

• GET /Consent/{id}

Summary of changes in YAML

{
Frequency:
	description: Defines frequency of FI data fetch within the defined time unit. E.g. HOURLY,DAILY,MONTHLY,YEARLY.
The maximum frequency value that can be defined is 1 request per HOUR. Similaraly it will be 24 requests per DAY and so on. Frequency can not be set below 1 request per hour.
	type: object
	
}

2. GET /Consent/{id}

Below changes are done in the response body i.e. Consent Artefact Model and SignedConsentDetail Model which is decrypted value of signedConsent field in ConsentArtefact model. Also, the ConsentDetail model is renamed to SignedConsentDetail for better clarity.

2.1. Referred fiTypes from common model FITypes

Related to change in POST /Consent API.

Summary of changes in YAML

{
fiTypes:
	$ref: '#/definitions/FITypes'
}

2.2. Added new enumeration value as USER in type field of DataConsumer element

Related to change in POST /Consent API.

Summary of changes in YAML

{
type:
	type: string
	description: Type of DataConsumer
	enum:
		- FIU
		- AA
		- USER //Added
	example: AA
}

2.3. Updated description of Frequency field.

Related to change in POST /Consent API.

Summary of changes in YAML

{
Frequency:
description: Defines frequency of FI data fetch within the defined time unit. E.g. HOURLY,DAILY,MONTHLY,YEARLY.
The maximum frequency value that can be defined is 1 request per HOUR. Similaraly it will be 24 requests per DAY and so on. Frequency can not be set below 1 request per hour.
type: object

}

3. POST FI/Request

Below changes are done in the request body i.e. Keymaterial Model which is referred in the FIRequest model.

3.1. Updated description of params, Nonce field and added an example

Why was this change needed? The exact cryptographic parameters to be used for end-to -end encryption are not mentioned explicitly in the API spec. This might cause interoperability issues.
What about the old fields? NA
Has any data changed? NA
What has changed in the API? Updated params field description in the KeyMaterial model with exact cryptographic parameters to be used as "cipher=AES/GCM/NoPadding;KeyPairGenerator=ECDH". Also, updated description of Nonce field to mention that Nonce should have a fixed length and added a reference on how Nonce should be formed
Other APIs impacted due to this change:

• GET /FI/fetch/{sessionId}

Summary of changes in YAML

{
params:
	type: string
	xml:
	attribute: true
	description: 'Specifies the secure standard cryptographic primitives to perform
	end to end encryption. Use Key-Value pair separated by a semicolon. The value
	given for cryptographic primitives in example should be used for symmetric
	encryption(AES-256 bits, GCM-128 bits and No Padding) and key exchangeprotocol(ECDH).'
	example: 'cipher=AES/GCM/NoPadding;KeyPairGenerator=ECDH'
}

{
Nonce:
	type: string
	example: '29512b70-ca84-46b5-9471-63765599cf15'
	description: 'Nonce is a random string generated every time during the publishing of
	Ephemeral public key to ensure that old communications cannot be reused in replay
	attacks.Nonce should have a fixed length. Unlike random numbers, random strings do
	not require byte ordering. Hence session keys can be generated in a platform
	independent way. Ref: https://tools.ietf.org/html/rfc5116'
}

4. GET /FI/Fetch/{sessionId}

Below changes are done in the response body i.e. Keymaterial Model and encryptedFI field which is referred in the FIFetchResponse model.

4.1. Updated description of params and Nonce field

Related to change in POST /FI/Request API.

Summary of changes in YAML

{
params:
	type: string
	xml:
	attribute: true
	description: 'Specifies the secure standard cryptographic primitives to perform
	end to end encryption. Use Key-Value pair separated by a semicolon. The value
	given for cryptographic primitives in example should be used for symmetric
	encryption(AES-256 bits, GCM-128 bits and No Padding) and key exchangeprotocol(ECDH).'
	example: 'cipher=AES/GCM/NoPadding;KeyPairGenerator=ECDH'
}

{
Nonce:
	type: string
	example: '29512b70-ca84-46b5-9471-63765599cf15'
	description: 'Nonce is a random string generated every time during the publishing of
	Ephemeral public key to ensure that old communications cannot be reused in replay
	attacks.Nonce should have a fixed length. Unlike random numbers, random strings do
	not require byte ordering. Hence session keys can be generated in a platform
	independent way. Ref: https://tools.ietf.org/html/rfc5116'
}

4.2. Removed line format:binary from encryptedFI field

Why was this change needed? The encrypted content in encryptedFI field was incorrectly considered as file data type instead of string after compilation.
What about the old fields? NA
Has any data changed? NA
What has changed in the API? removed line format:binary from encryptedFI field of FIFetchResponse model.
Other APIs impacted due to this change:

• GET /FI/Fetch/{sessionId} from Experimental FIP API

Summary of changes in YAML

{
encryptedFI:
	type: string
	format: binary //Removed
	description: Contains the encrypted financial information based on the
                      key material defined corresponding to the user's Account.
}

5. Common changes

5.1. Removed line format: byte

Why was this change needed?
format:byte is specified for x-jws-signature header and signedConsent field. Hence the string will be considered as base64 encoded string. However the format is not correct as JWS signature contains multiple base64 encoded strings connected with "." (dot). This might cause issue while compiling.
What about the old fields? NA
Has any data changed? NA
What has changed in the API? Removed format: byte
APIs impacted due to this change:

• POST /Consent
• GET /Consent/handle/{consentHandle}
• GET /Consent/{id}
• POST /FI/request
• GET /FI/fetch/{sessionId}
• POST /Consent/Notification
• POST /FI/Notification
• POST /Account/link/Notification

Summary of changes in YAML

{
	format: byte // Removed
}