The standard client requires that the client application capture the username and password information, storing it as needed, then present it to the YouMail authentication service on behalf of the end user. To use this mechanism, you will first ask the user to provide their credentials (phone number and pin).
The following URL and HTTP method should be used:
The following parameters are required to be provided as part of this URL:
|Uid||The user's YouMail user id. This is either the username or the phone number of the account.|
|Pin||The user's PIN number they use to authenticate for both the web-based and phone-based features of YouMail. YouMail PINs are numeric.|
curl -X GET -H "Accept: application/xml" http://api.youmail.com/api/v3/authenticate/0001112222:1234
If the authentication is successful, YouMail will return an HTTP status of 200. The HTTP response for a successful authentication is a simple xml response containing a single value as follows:
This token can then be used in as an authorization header for all requests to YouMail.
Authorization: YouMail cQpvfV1GIQmn0cogbT1C9fvmaM6SGiKrzVdkDUHFwxZRSfxbibF4
Or the token can be passed along in the query string of any request to the API server.
If there is an error authenticating the user, YouMail will return an HTTP status 403. The response body is a simple xml response containing an error code in the following form:
<?xml version="1.0" encoding="utf-8"?> <authenticationResponse> <errors> <error> <errorCode>token</errorCode> <shortMessage>string</shortMessage> <longMessage>string</longMessage> </error> </errors> <timestamp> dateTime </timestamp> </authenticationResponse>
The following are possible error codes:
|InvalidUser||The username, phone number or PIN were not recognized by YouMail, either as existing, or being valid for the user if the user account does exist.|
|AccountDeleted||The account has been deleted.|
|ServiceUnavailable||The service is not available, try again later.|
|Unknown||An unknown error has occurred; perhaps the request contained a malformed URL or badly formed input.|
Authentication tokens have a fixed lifetime. When they expire a new token must be obtained per the above method. YouMail will signal that the authToken has expired by returning a 403 HTTP Status Code.
Use of a bad authentication token will result in a 403 status code and a “InvalidAuthToken” error in the response content.