Inswitch APIs authentication and authorization is based on two levels, the first level is the use of API Key for channel authentication and the second level is the use of oAuth 2.0 for Entity authorization, see Wallet section for more information about Entities .

Since all Inswitch products are based on our Core Banking Platform, there must always be at least one entity present to represent the merchant's account. Thus, to use the API, an API key must be provided and OAuth 2.0 authentication must be performed.

The API Key should be pass in all API calls as the header apikey, additionally a token should be passed in the X-User-Bearer header. The token is obtained using the Auth_Service API

Auth Service API

The Token Auth-Service API return two tokens:

• access_token: it should be used in all API calls
• refresh_token: it just helps you to login a user without them having to re-enter their login credentials multiple times. The access token is re-issued, provided the refresh token is a valid one requesting permission to access confidential resources.

By default, the access token expires after 5 minutes, and the refresh token expires after 30 minutes. However, both expiration times can be adjusted to meet the specific needs of the merchant. While the access token is active, it can be used multiple times.

Get Access Token with credentials

curl --location --request POST 'https://{{baseUrl}}/auth-service/1.0/protocol/openid-connect/token' \
--header 'apikey: {{apikey}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username={{username}}' \
--data-urlencode 'password={{password}}'

{
    "access_token": "{{access_token}}",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "{{refresh_token}}",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "{{session_state}}",
    "scope": "profile email"
}

Get Access Token with refresh token

curl --location 'https://gateway-am.apps.ins.inswhub.com/auth-service/1.0/protocol/openid-connect/token' \
--header 'apikey: {{apikey}}’ \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token={{refresh_token}}’

{
    "access_token": "{{access_token}}",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "{{refresh_token}}",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "{{session_state}}",
    "scope": "profile email"
}

Best Practices

In order to improve the performance of the platform avoid calling get access token with credentials for every API call that is needed. The recommended flow is:

To validate whether the token is valid (i.e., has not expired), the merchant can either control the expiration time or decode the JWT Token to view the 'exp' parameter, which indicates the expiration date in Unix format (GMT). The access token and refresh token can be updated whenever a new token is requested.