Without authentication you will not be able to establish a connection to Ricardo. For authentication you first of all require a partnership key. If you do not have one, you can apply for it. You will receive a token which will enable you to use the different services..
- The partnership credentials “partnership key” and “partnership password” identify you on the Ricardo platform.
- The credentials must be transmitted every time you call a method of the security Service; otherwise you will receive an error message.
- You need unique partnership credentials for each application you build. For example, if you want to build an app for iOS and one for Android devices, you need partnership credentials for each.
- For each language available on your application you need separate partnership credentials (German and French are the options).
- It is prohibited to transmit the partnership key to third parties. If Ricardo detects that partnership credentials are used by more than one application, Ricardo will revoke the authorization.
- Token credentials represent both the Ricardo customer or the anonymous user and the partnership.
- They are only composed of a key. There is no associated password.
- Please respect the two elements: SessionDuration and TokenExpirationDate.
- Session Duration:
The duration (in minutes) during which the token can be used. Every time you use this token, the session duration is reinitialised to its default value. If you try to use the token after the session duration has expired, you will receive an error message stating that your token has expired and must be refreshed. You can do that by using the Refresh Token Credential method of the Security Service.
- Token Expiration Date:
Date after which the token can no longer be used. You will have to request a new token. The token expires after 180 days (6 months) or immediately if you changed your Ricardo password. This rule obtains also, if you use a single-user-token.
All the methods you need can be found in the Security Service (SOAP, JSON). You have to identify all your calls to this service with your partnership credentials:
//you have to insert your Partnership Credentials into the HTTP Header: httpWebRequest.Headers.Add("Ricardo-Username: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX"); httpWebRequest.Headers.Add("Ricardo-Password: Password");
client = new SecurityServiceSoapReference.SecurityServiceClient("WSHttpBinding_ISecurityService"); ((SecurityServiceSoapReference.SecurityServiceClient)client).ClientCredentials.UserName.UserName = "Your Partnership credential Username"; ((SecurityServiceSoapReference.SecurityServiceClient)client).ClientCredentials.UserName.Password = "Your Partnership credential Password";
You need to call this method: GetAnonymousTokenCredential.
1. Ask for a temporary credential:
With this method you get the temporary credential ID: CreateTemporaryCredential.
- TemporaryCredentialKey: The TemporaryCredentialKey needed to obtain the ConsumerToken.
- ValidationUrl: Link to the authorisation page.
- ExpirationDate: Limit date for using the temporary credential ID.
2. Redirect the customer:
The customer has to validate the temporary credential. You will have to redirect him or her using the ValidationUrl.
3. Get the consumer token:
Once the customer has validated your temporary credential, you will have to call the method: CreateTokenCredential. Then enter the temporary credential key.
- TokenCredentialKey: Represents the username for consumer services authentication.
- TokenExpirationDate: Limit date for using this access. Once it has expired, you will have to request a new temporary credential.
- SessionDuration: After this duration of inactivity, the consumer token will need to be refreshed.
If you retrieve a MessageSecurityException with a FaultException message “Session expired”, it means that the session for this token has expired (< 180 days). You can refresh it using the method: RefreshTokenCredential. Enter the consumer token key.
But if the consumer token expiration date has been reached (> 180 days), you will get a BusinessFault message “Invalid TokenCredential”. In this case, you will need to request a new temporary credential and repeat the whole consumer token process.
Some critical methods are protected by an antiforgery token. It prevents a man-in-the-middle replaying the calls and fraudulently impacting the platform. To obtain an antiforgery token, you have to call the method: CreateAntiforgeryToken.