API Authentication
Overview
"Authentication" refers to the process of verifying that the person requesting a service is, in fact, who he says he is. Within Messaging, authentication is handled by an open standard protocol called OAuth 2.0. This protocol was designed specifically for HTTP, and provides standard mechanisms to allow REST API users to request access to a particular service.
Authentication with OAuth 2.0 consists of several steps. In the first step, the end-user obtains a "Consumer Key" and a "Consumer Secret." The Consumer Key is analogous to a username, and is considered public information; the Consumer Secret is analogous to a password, and is kept confidential. Both of these pieces are managed at the user level, and can be obtained from the API Keys screen.
OAuth 2.0 supports a handful of different methods called "grant types" for granting access to a requested service. Messaging utilizes only one grant type: "Password Credentials." The second step in the authentication process involves using this grant type to request a "token." A token is a text string that, when provided in a request message, will allow the user access to the requested service. Tokens are valid only for a certain period of time. By default, Messaging tokens expire after eight hours, but you can optionally adjust this duration.
The OAuth 2.0 protocol defines several different types of tokens. Messaging uses the most common type of token, known as "bearer." A bearer token is a randomly-generated text string without any sort of encryption key. When you use this token to make an API service call, you are assumed to be the owner, or "bearer" of the token.
Token Request Message
To get a token, you must provide your credentials (the Consumer Key and Secret) directly to the authentication server via a POST request. If these credentials are valid, the server replies back with the token. This message must be submitted using the POST method, with a Request Content Type of <application/x-www-form-urlencoded>.
To request a token, send a request message using the POST method, to the following URL:
https://api.eccmp.com/services2/authorization/oAuth2/Token
The request message must contain the following parameters:
Keyword |
Required |
Description |
username |
Required |
Your Consumer Key, found on the API Keys screen |
password |
Required |
Your Consumer Secret, found on the API Keys screen |
client_id |
Optional |
If used, must be set to your client identifier, which can be found on either the Edit User Access Rights screen or the API Keys screen |
grant_type |
Required |
"password" (no quotes) |
Below is a sample token request message:
POST https://api.eccmp.com/services2/authorization/oAuth2/Token HTTP/1.1
Host: api.eccmp.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 98
username=NTcwNjozOTQ=&password=1c106f90ec274340bde50ea78f410422&client_id=5706&grant_type=password
If your call fails, you'll receive an error response message, indicating that the token has not been generated. If your call is successful, you'll receive a response message in JSON format containing the following information:
Keyword |
Description |
access_token |
The OAuth 2.0 token. |
token_type |
This value will always be “bearer." |
expires_in |
Lifetime of the token in seconds. |
refresh_token |
This parameter is not currently used. |
Below is a sample token response message (for the sake of readability, the token depicted here is much shorter than what a real token would be):
{
"access_token":"AAEAAG39ZdZRoGDRZJggMdv43pxrIVokFD57mhz03ncF",
"token_type":"bearer",
"expires_in":28800,
"refresh_token":"h8fR!IAAAAFMbAP2AWWeil7JS9YKx3mURSZypddIawaUJQpBjUYarGI2g"
}
With your valid token, you can now begin making API service calls, utilizing any of the platform's REST endpoints. The token must be provided within the header of each of your web service calls. Each call must contain an authorization to Bearer type, followed by your token text string.
Below is an example of an HTTP header:
Authorization: Bearer 123456789761657894564564fh7rgjuhsrn56yu4567y56re4qnu56sr
As noted above, your token will expire after a set period of time. If you attempt an API request call, and your token has expired, you'll receive a response message with the "401 - Unauthorized" response code. At this point, you'll need to repeat the steps described above to request a new token. Once you've received this new token, you can begin making API request calls again.