Fax API v3.0

RESTful API for eFax Services

OAuth2 Authentication

The Fax API is using OAuth2 as authenticaiton method. You need to get an Access Token from the OAuth2 server, in order to access the Fax API functions.

Before You Get Started

To use OAuth2 to authorize your application to access Fax API, the following information is needed. You could contact MaxMD tech support to get your testing credentials.
  • username: The MaxMD TUser account username
  • password: The MaxMD TUser account password
  • client_id: The client id identifies your application to authentication server.
  • client_secret: The client secret.
  • redirect_uri: Once an authorization code is generated, MaxMD OAuth2 server will redirect to the {redirect_uri} with generated code.

OAuth2 Parameters

Parameter Name Description
scope tuser.fax
Permission to use the TUser Account to use Fax API
Authorize Endpoint https://api.maxmddirect.com/oauth/authorize
Token Endpoint http://api.maxmddirect.com/oauth/token

Obtain Authorization Code

Generate authorize URL

Genereate Authorize URL: https://api.maxmddirect.com/oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&scope=tuser.fax&response_type=code .

Then redirect user to the generated Authorize URL. The user will be asked to authenticate to the OAuth2 server, and decide whether to grant your application the requested permission.

Your application doesn't need to do anything at this stage as it waits for the response from MaxMD OAuth2 server indicating whether the access was granted.


Example - Enter the parameter into the following form to generate a sample authorize link.

client_id
redirect_uri
scope
response_type

Sample Authorize URL:

Handle Authorize Server response

If the user approves the request, then the response contains an authorization code. Like the following example:
https://callback.mydomain.com/?code=53c9b090e8154b12a5199d8ea05b7d65

Exchange authorization code for refresh token and access token

After your application receives the authorization code, it can exchange authorization code for an access token by using the following token endpoint. The token endpoint will validate the authorization code, and generated refresh_token and access_token.

POST http://api.maxmddirect.com/oauth/token

HTTP Request Header

Content-Type: application/x-www-form-urlencoded

HTTP Request Body FORM Parameters

grant_type: authorization_code
client_id: {client_id}
client_secret: {client_secret}
code: {authorization code}

HTTP Response (application/json)

access_token: The token to be used for CA API functions. This token expires in one hour
refresh_token: The refresh_token could be used to refresh access_token without the user being involved. You must save this refresh_token securely.
token_type: Bearer
expires_in: access_token TTL

Sample Codes:

Refreshing an access token

Access tokens expires in one hour. You can refresh an access token by using the following endpoint without prompting the user for permission.

POST http://api.maxmddirect.com/oauth/token

HTTP Request Header

Content-Type: application/x-www-form-urlencoded

HTTP Request Body FORM Parameters

grant_type: refresh_token
client_id: {client_id}
client_secret: {client_secret}
refresh_token: {refresh_token}

Http Response (application/json)

access_token: The token to be used for CA API functions. This token expires in one hour
refresh_token: The refresh_token could be used to refresh access_token without the user being involved. You must save this refresh_token securely.
token_type: Bearer
expires_in: access_token TTL

Sample Codes:

Use access token

Access Token will be used in each HTTP Request Header Authorization: Bearer {access_token}

Click here for Send Fax function.

Click here for Get Fax Message(s) functions.

Click here for List Fax Numbers function.