Authentication v2

This section is intended to describe authentication way to interact with SwiftFederation APIs.

1. Authorization Header and Format

  • Authorization Header Definition
Field Description
signatureAlgorithm Signature Algorithm. E.g. HMAC-SHA256
accessKeyId Access key id that is assigned to customer to call APIs.
signature Signature is the string which is signed based on request headers, request path, request method, access key ID and request body with access key secret. Please refer to Signature Algorithm v2.
Note: Customer or Partner can view access key ID and access key secret on SwiftFederation portal.
  • Authorization Header Format
Authorization:${signatureAlgorithm} ${accessKeyId}:${signature}


Signature Algorithm

  • Canonical header string

To create the canonical headers list, convert all header names to lowercase and remove leading spaces and trailing spaces. The following pseudocode describes how to construct the canonical list of headers:

CanonicalHeaders = ''

headers=()
headers.append('host')
for header in request.getHeaders():
  if header.startwith('x-sfd-'):
    headers.append(header)

for header in sort(lowercase(headers)):
  CanonicalHeaders += lowercase(header) + ':' + request.getHeader(header) + '\n'

Build the canonical headers list by sorting the (lowercase) headers by character code and then iterating through the header names. Construct each header according to the following rules:

  1. Append the lowercase header name followed by a colon.
  2. Append a comma-separated list of values for that header. Do not sort the values in headers that have multiple values.
  3. Append a new line ('\n').

Note: You must include the host header at a minimum.

  • Canonical signing string

The signing string is assembled as below:

uppercase(${HTTPMethod})+"\n"+
${URI}+"\n"+
${CanonicalHeaders}+"\n"+
${accessKeyId}+ "\n"+
${requestBody}

Example Original headers

GET /v1.2/customer/1 HTTP/1.1
Host:base-api.swiftfederation.com

Authorization:HMAC-SHA256 6vE59B1z4p174N25:01888fad3a9f683540c5462c64022737217c2e1d873a39b177028213ebdb4d65
Content-Type:application/json; charset=utf-8
X-SFD-Date:20180926T131000Z
X-SFD-Nonce:69527
X-SFD-Signature-Version:2
X-SFD-FZone:SG

Example Canonical form request

GET\n
/v1.2/customer/1\n
Host:base-api.swiftfederation.com\n
X-SFD-Date:20180926T131000Z\n
X-SFD-FZone:SG\n
X-SFD-Nonce:69527\n
X-SFD-Signature-Version:2\n
accessKeyId:6vE59B1z4p174N25
Note1: Request method should be converted to uppercase, e.g. GET.
Note2: "\n" means 0x0A, LR.
Note3: Put request parameter in ${requestBody} to do signature when http request method is 'GET'.


  • Generate Signature

Calculate signature of signing string by using HMAC-SHA256 algorithm with access key secret. And then use hex to encode signature to string.

byte[] signatureBytes = hmacSha256(${accessKeySecret}, ${signingString}); 

String signature = Hex.encodeHex(signatureBytes);

2. Example

2.1. Request Example

Assume that AccessKeyID is 6vE59B1z4p174N25 and AccessKeySecret is 28G5nC2zw143m25026n9H11PwNYs4576.

  • Original Request
GET /v1.1/customer/1 HTTP/1.1
Host:base-api.swiftfederation.com
Authorization:HMAC-SHA256 6vE59B1z4p174N25:01888fad3a9f683540c5462c64022737217c2e1d873a39b177028213ebdb4d65
Content-Type:application/json; charset=utf-8
X-SFD-Signature-Version:2
X-SFD-Date:20180926T131000Z
X-SFD-Nonce:69527
X-SFD-FZone:SG
  • Calculate Populate signing string
"GET"+"\n"+"/v1.1/customer/1"+"\n"+"host:base-api.swiftfederation.com"+"\n"+"x-sfd-date:20180926T131000Z"+"\n"+"x-sfd-fzone:SG"+"\n"+"x-sfd-nonce:69527"+"\n"+"x-sfd-signature-version:2"+"\n"+"accessKeyId:6vE59B1z4p174N25"+"\n"+""

=>

GET
/v1.1/customer/1
host:base-api.swiftfederation.com
x-sfd-date:20180926T131000Z
x-sfd-fzone:SG
x-sfd-nonce:69527
x-sfd-signature-version:2
accessKeyId:6vE59B1z4p174N25
  • Calculate Signature
Signature=Hex.encodeHex(hmacSha256("28G5nC2zw143m25026n9H11PwNYs4576", "GET"+"\n"+"/v1.1/customer/1"+"\n"+"host:base-api.swiftfederation.com"+"\n"+"x-sfd-date:20180926T131000Z"+"\n"+"x-sfd-fzone:SG"+"\n"+"x-sfd-nonce:69527"+"\n"+"x-sfd-signature-version:2"+"\n"+""))

Signature=01888fad3a9f683540c5462c64022737217c2e1d873a39b177028213ebdb4d65
  • Final Request
GET /v1.1/customer/1 HTTP/1.1
Host:base-api.swiftfederation.com

Authorization:HMAC-SHA256 6vE59B1z4p174N25:01888fad3a9f683540c5462c64022737217c2e1d873a39b177028213ebdb4d65
Content-Type:application/json; charset=utf-8
X-SFD-Date:20180926T131000Z
X-SFD-Nonce:69527
X-SFD-FZone:SG
X-SFD-Signature-Version:2
           Updated 2024-08-26 10:16:22

results matching ""

    No results matching ""