This scenario requires the interaction of your system with our Authentication Page before engaging any interaction with other producers' APIs in order to obtain an AuthToken that allows you to provide proof of authentication that your user is actually requesting the operation you are about to perform.
In this scenario you will be required to manage two security elements:
- API Key An application key, in the form of a 34-byte base-64 alphanumeric string, like
4MSI5FGCXK5UVV2U487A08OZH4NHCHTKS. - AuthToken An authentication token, in the form of a 256-byte base-64 alphanumeric string, like
634a3b26dd4f ... 2cPWqcZVUfG01D2. Each AuthToken is generated by following the instructions illustrated in Step 1 (see below figure).
The following diagram describes the interaction between the main actors:
Step 1. Authentication session initialization
This step is required in order to initialize the authentication session for the user. Each API request must be issued by specifing the following headers:
Content-Type: "application/json"
Auth-Schema: "S2S"
Api-Key: "{Third Party APIKey}"
You must invoke the POST Create Auth Session API, passing the correct producerId:
Request:
POST https://api.platfr.io/api/fabrick/platform/v3.0/s2s-auth/producers/{producerId}/auth-sessions
Body:
{}
Response:
HTTP/1.1 200 OK
{
"status": "OK",
"errors": [],
"payload": {
"sessionId": "SessionID",
"accessToken": "AccessToken"
}
}
The response to the POST Create Auth Session call contains the sessionId and the accessToken parameters required to proceed in the next steps.
Step 2. User's browser redirection
In this step, you have to redirect the user's browser (either the actual Internet browser, or a specific-purpose web view on a mobile application) in order to display the authentication page.
The URL that has to be used to access the authentication page is the following:
SANDBOX ENVIRONMENT
GET https://sandbox-auth.platfr.io/producers/{producerId}/?sessionId=SessionID&accessToken=AccessToken
LIVE ENVIRONMENT
GET https://auth.platfr.io/producers/{producerId}/?sessionId=SessionID&accessToken=AccessToken
Where producerId, sessionId and accessToken must be properly set with respect to the previous step.
Please note that the authentication page requires that the following header must be correctly set in order to work properly:
X-Forwarder-For: <IP addresses>
This header is usually set automatically when issuing the request; however, please take care of this requirement in order to set up a correctly working system.
Step 3. User interacts with the authentication page
This step takes place outside your control scope. The user interacts with the authentication page providing answers to the authentication challenges requested by the producer in order to correctly authenticate.
Step 4. Authentication session finalization
After the user has provided all the correct answers to the authentication challenges, a login success page is displayed to the user. In this page, the user can also select the operation permissions granted to the third party. If the user has previously authenticated with the same producer, such permissions may be reviewed. For further information about operation permissions, please refer to the User Permissions section.
Behind the scenes, Platform performs a callback to your custom URL to terminate the authentication session. The custom URL can be configured in your private profile. Usually, the URL is structured as follows:
https://ThirdPartyURL?sessionId=SessionID&refreshToken=RefreshToken&authToken=AuthToken
The sessionId parameter should be used to match the user session, the refreshToken parameter contains the RefreshToken to be used (optionally) to invoke PUT Refresh AuthToken to refresh the AuthToken, while the authToken parameter contains the AuthToken required to proceed in Step 5.
Step 5. Authenticated operation
Once you have obtained the AuthToken for your user, you can invoke the API required to perform the correct operation.
Each API request must be issued by specifing the following headers:
Content-Type: "application/json"
Auth-Schema: "S2S-AUTH"
Api-Key: "{Third Party APIKey}"
Auth-Token: "{User AuthToken}"