Obtaining Authentication Credentials
At this time there are two different authentication approaches used for the Fax Services and Admin APIs.
The Admin API uses current eFax Corporate Admin account credentials to validate API users. As part of each call made to the host endpoint, the API user passes in as part of the Request header their Admin ID (AccountID), their username, and their password. Calls containing valid credentials are allowed to proceed.
Access to the Fax Services API, on the other hand, is tightly controlled through the industry-standard OAuth2 protocol for authentication and authorization. Users of the Fax Services API must obtain a bearer token, using their API Key and App ID, and then pass that token in as part of each Fax Services API call they make. Tokens must be refreshed every 24 hours.
Obtaining Usage Credentials for the Admin API
When a user is given administrative access to eFax Corporate, they are given a unique username, password, and AccountID. These same credentials are used to make calls to the Admin API. Only calls with valid credentials in the Request are permitted.
Obtaining Usage Credentials for the Fax Services API
The Fax Services API supports the OAuth2 protocol for authentication and authorization, which requires that the user credentials being passed to the POST /tokens operation use HTTP Basic Authentication.
This API supports the OAuth2 protocol for authentication and authorization, which requires that the user credentials being passed to the POST /tokens operation use HTTP Basic Authentication.
To use the API, users must generate an API Key, then, using that key in conjunction with their App ID, obtain a bearer token. That token is then passed in as part of each API method they call, along with a valid user-id.
Tokens expire after 24 hours. When your token expires, repeat the steps below to generate a new one for use with all subsequent API calls.
Step 1 – Generate Your API Key and Collect Your APP ID
At this time, you must contact Sales Engineering to create/reset your API Key. Click the Generate button for details.
It is important that you also know your User ID. This will be sent to you in a separate email (not in the Welcome email containing your App ID). If you do not receive your User ID, contact your Application Provider administrator or contact Support at [email protected].
Step 2 - Obtain Your Bearer Token
Obtain your bearer token by making a POST /tokens request using Basic Authentication with your credentials from Step 1.
- The request must be a HTTP POST request.
- The request must use Basic Authentication using App ID as the username and API Key as the password.
- The request must include a Content-Type header with the value of application/x-www-form-urlencoded;charset=UTF-8.
- The body of the request must be grant_type=client_credentials.
The HTTP Basic Authentication protocol requires a username and password; in the eFax Enterprise API, the App ID is the same as the username, and the API Key is the equivalent of the password. In other words, App ID:API Key is the same as Username:Password.
A curl Example
The following curl sample is used to generate a bearer token:
curl --request POST \ --url https://api.securedocex.com/tokens \ --user 'app-id:api-key' \ --header 'content-type: application/x-www-form-urlencoded;charset=UTF-8' \ --data 'grant_type=client_credentials'
Receiving a Response
Upon successful authentication, the client/partner receives the following response:
HTTP/1.1 200 OK Status: 200 OK Content-Type: application/json; charset=utf-8
{
"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.TCY
t5XsITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUcX16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtj
PAYuNzVBAh4vGHSrQyHUdBBPM",
"token_type": "bearer", "expires_in": 86399, "scope": "read write", "jti": "8ea4457d-a26e-49a6-91d0-26e3d4edeb84" }
Use the access token returned to exercise the other methods in the API, as described below.
Step 3 - Make API Calls with Bearer Token
The API methods can now be called using the bearer token. To do so, construct a normal HTTPS request and include an Authorization header with the value of Bearer <token value from Step 2>. In addition to the token, include the user ID for the user whose faxes are part of the request (other data values may be needed depending on the call in use).
For example, when calling the API method GET faxes/received for User ID 95173361-95173340:
curl --GET https://api.securedocex.com/faxes/receivedAuthorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAy Mn0.TCYt5XsITJX1CxPCT8yAV-TVkIEq_bChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUcX16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTw LtjPAYuNzVBAh4vGHSrQyHUdBBPM
-H "user-id: 95173361-95173340
Returns:
{
"total_records": 2,
"first_record": 1,
"last_record": 2,
"faxes": [
{
"fax_id": "0ae7a8a6-c51f-4efa-b352-a6cf67cdca40",
"pages": 1,
"image_downloaded": true,
"fax_status": "STORED",
"completed_timestamp": 2024-04-19T12:36:08.000+0000",
"originating_fax_number": "UNKNOWN"
}, {
"fax_id": "4389e2e0-0a7b-4b0b-9688-253d66432c16",
"pages": 1,
"image_downloaded": true,
"fax_status": "STORED",
"completed_timestamp": "2024-04-19T12:36:08.000+0000",
"originating_fax_number": "UNKNOWN"
}
]
}
Now that you are ready to use the eFax Enterprise API, you'll need to understand its System Characteristics, including allowable message sizes, supported file types, and send transmission error codes.