User Tools

Site Tools


Sidebar

apiv3:authentication_api:authenticating

Authenticating

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).

Request Info

The following URL and HTTP method should be used:

HTTP Method URL
GET https://api.youmail.com/api/v3/authenticate/{Uid}:{Pin}

The following parameters are required to be provided as part of this URL:

Parameter Description
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.

Example Request

curl -X GET -H "Accept: application/xml" http://api.youmail.com/api/v3/authenticate/0001112222:1234

Successful Authentication

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:

<authToken>cQpvfV1GIQmn0cogbT1C9fvmaM6SGiKrzVdkDUHFwxZRSfxbibF4</authToken>

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.

https://api.youmail.com/api/v3/...?authtoken=Ae7mb981beajF00mnBZeeQ

Failed Authentication

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:

Parameter Description
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.
TermsNotAgreed The user has not agreed to the YouMail terms of use. The user will need to visit YouMail directly to agree to the terms of use before they can continue.
AccountExpired The account has been expired, whether through inactivity or a violation of YouMail terms of use. The user will be unable to authenticate with this account and must obtain a new account.
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.

Notes

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.

apiv3/authentication_api/authenticating.txt · Last modified: 2016/05/19 15:49 (external edit)

Page Tools