Authentication
Previous page API Providers
Next pageWeb Server Configurations
As API provider, you want to ensure that access to your API service is authorised and secured. When API consumer sends an API request to your API service, the request reaches the Swift API Gateway and then it is forwarded to your API service. Swift API Gateway is the client who will establish a secure session with your API service. Similar to how Swift API services are protected and secured, we ensure the same security measures are also provided to support and protect external API providers. These security measures are from the network level as well as the application level. The network level security is guaranteed by mTLS and the application level security is guaranteed by OAuth 2.0 authorisation framework. You can choose to instrument one or both depending on your security requirements.
Mutual TLS (mTLS) extends Transport Layer Security (TLS) by requiring both the Swift API Gateway (client) and the API provider (server) to authenticate each other using digital certificates before establishing a secure connection. Unlike standard TLS, which only verifies the server, mTLS enhances security by enforcing bidirectional authentication. The digital certificates used vary based on the network from which the API service is accessed.
For API services consumed through MV-SIPN, the web server certificate should be issued by Swift Certificate Authority (SwiftNet CA) with distinguished name (DN) created by Swift during registration. Refer to Web Server Certificates with a step-by-step guide to create this certificate.
Swift CA like other public Certificate Authorities, issues X.509 digital certificates to trusted parties. The commands used to generate the certificate are the same as for any other certificates but the certificate must be signed by the Swift CA instead of a public CA.
For API services consumed through internet, the server certificate used by the API service provided by the API provider should be issued by a publically trusted Certificate Authority (CA). The client certificate used by the Swift API Gateway to authenticate with API services is issued by DigiCert, a well-known public CA. DigiCert's root certificates are included in the trust store of most browsers and operating systems, so there is usually no need to install the root certificate. If you need to install it seperately, refer to the download links below.
DigiCert Root Certificate:
The certificate details are:
| Parameter | Value |
|---|---|
| Valid until | 10/Nov/2031 |
| Serial Number | 08:3B:E0:56:90:42:46:B1:A1:75:6A:C9:59:91:C7:4A |
| SHA1 Fingerprint | A8:98:5D:3A:65:E5:E5:C4:B2:D7:D6:6D:40:C6:DD:2F:B1:9C:54:36 |
| SHA256 Fingerprint | 43:48:A0:E9:44:4C:78:CB:26:5E:05:8D:5E:89:44:B4:D8:4F:96:62:BD:26:DB:25:7F:89:34:A4:43:C7:01:61 |
In addition to mTLS, API providers can opt in for an additional layer of protection using OAuth 2.0 authorisation framework to further secure their API service. The supported grant type is client credential. The following is a general guideline for API providers upon receiving authentication requests from the Swift API Gateway.
API providers should provide OAuth 2.0 authentication details using the API provider OAuth integration form.
Consider validating the following parameters to handle bad requests appropriately:
If the previous validation is successful, a successful response containing the granted token and other required parameters should be returned in JSON format.
| Required parameters | Descriptions |
|---|---|
| access_token | The issued access token. |
| token_type | This should be Bearer. |
| expires_in | Value in seconds. For example, 1800 for expiration in 30 minutes. |
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token": "2YotnFZFEjr1zCsicMWpAA",
"token_type": "Bearer",
"expires_in": 1800
}If the previous validation is not successful, an error response containing the standard OAuth error and error description should be returned in JSON format.
| Required parameters | Descriptions |
|---|---|
| error | Standard OAuth errors defined in RFC6749. |
| error_description | Description of error with more details. |
See below a list of error scenarios and suggested error and error_description.
| Error Scenario | Status Code | Standard OAuth Error | Error Description |
|---|---|---|---|
| Malformed request | 400 | invalid_request | OAuth token grant request is malformed. |
| Client (application) authentication failed (unregistered API key or invalid secret) | 401 | invalid_client | Client application cannot be authenticated. |
| Requested grant type is not urn:ietf:params:oauth:granttype:client-credentails | 400 | unsupported_grant_type | Only Client Credentials and refresh grant types honoured here. |
| Client application is not registered for, or authenticated user has no roles for, requested scope, or requested scope is malformed | 400 | invalid_scope | Access to requested scope cannot be granted. |
| Any internal error | 400 | temporarily_unavailable | Request cannot be processed at this time. Please try again. |
When the "invalid_client" error occurs, API provider should set the response header WWW-Authenticate to Basic realm="any string literal value".
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"error": "invalid_client",
"error_description": "Client application cannot be authenticated"
}