(This document has a new title. The previous title was "Intel® Cloud Services Platform Gateway REST API Reference".)
Example Request - Application Authorization
Code Example - Application Authorization
Example Request - User Authorization
Code Example - User Authorization
If you are looking for an overview of authorization for applications using the Intel® Cloud Services Platform beta REST interfaces, you have come to the right place. The information covered here includes establishing sessions using application authorization via the Intel Cloud Services Platform API Management layer or using user authorization via Intel® Identity Services. You can also find reference information that applies to authorization for all the REST services here.
Getting Started and API Reference information for specific services is provided in Developer's Guides and API Reference documents for those services. You can find that information on the Intel Cloud Services Platform beta portal.
Services Authorization
All applications begin by authorizing with an agent of Intel Cloud Services Platform to obtain an access token, regardless of which services the application uses. Apps must include this access token in all subsequent calls during the session.
Apps can request two types of authorization:
- Application authorization. With application authorization, the app does not know the user's identity (or does not wish to use it). This level of authorization allows services to provide basic features to apps. For application authorization, the API Management layer is the agent that performs authorization, provides an application authorization access token to the app, and manages the session that it establishes.
- User authorization. In this case, the app knows and wishes to use the user's identity information. For user authorization, Intel Identity Services function as the agent to perform authorization (which includes involving the user in the process via UI screens). The user must authorize sharing of their information with the app before Intel Identity Services provide a user authorization access token to the app. Once the session is established, the API Management layer manages the session.
The specific capabilities available for application vs. user authorization vary depending on the REST services, as shown in the table below
| Services | Application Authorization | User Authorization |
|---|---|---|
| Location Based Services | Apps can provide most of the geocoding/reverse geocoding, routing, POI search, and static map creation capability for all users. | Apps can allow logged in users to save/retrieve a user's POI (Points of Interest) queries and Route queries, to retrieve this past search history, to present enhanced POI information, or wants to use GeoFences and GeoMessages. |
| Commerce Services | Apps can create carts, get cart info, update carts, check status of carts, and calculate taxes on carts. Apps can also get order info, process refunds, and get billing profile info. | Apps can perform all tasks under Application Authorization, plus can submit carts for purchase (Put/Post Cart Purchase). |
| Context Services | Apps can browse the catalog of information types. | Apps can access the context information for the supported information types. |
| Curation Services | n/a | All apps use user authorization because user data is accessed for all capabilities. |
| Catalog Services | All apps use application authorization only, because user data is not accessed. (Only the application is authorized for this service.) | n/a |
Application Authorization
For application authorization, all apps begin by authorizing with the Intel Cloud Services Platform API Management layer. The figure below shows the flow for application authorization. The API Management layer checks the client_id and client_secret provided and determines which services the app has subscribed to. The API Management layer establishes a services session and returns an application authorization token that is valid for the current session. Apps must include this access token in all subsequent calls during the session.
Applications make the subsequent calls to specific services URIs, but the calls are also automatically checked by the API Management layer to ensure that the app has subscription rights. The API Management layer also ends sessions when access tokens expire. (A refresh token provided along with the access token can be used to renew an expired session.)
When requesting a session from the API Management layer, the app always passes a client_id and client_secret in the URI. Developers obtain these values from the Intel Cloud Services Platform portal when they register their app. Developers must also subscribe to the specific services that their app will use. A third parameter, grant_type, is also required to authenticate with the API Management layer.
Apps use the HTTP Accept: header to request the format of the response (JSON or XML). XML is the default for the API Management layer if no response format is specified. (All the services support JSON only, except for Intel Identity Services, which support JSON and XML.)
Note: Because tokens are long, in API calls we usually substitute {access_token} or {refresh_token} for the real tokens. For calls that include elements like Client ID, Client Secret, and User ID, we usually substitute {client_id}, {client_secret}, and {user_id} for the real elements. In some cases, like initial use, we may show the real token or element. An example access_token is shown below:
2/gAAAAB-gK_mJ8IW5-PQX8LkMkHXAl4viM0vRppECIkBVmfR1SOeQgvhLQnQzrwWKnbbsW1AKBzKss6eD0H3p0HMtIwtbgFQpeiqf0hDUEQlXTbt4UpKphIcV95Gc0C3PtkgNboV1TLGCC_bu5gLFXQJGAhmB6lkcJ5UwHGyn8BxFoayTdAEAAIAAAACDjEGPraEwMdWDz5MHNkulggsPdX41i4dMrdVcQdSBOcAP9vt9n0GwVNnJljsSCOH4UNHjosPpm7iwcOfF_4i_4InxRa-jRC0RWJWMxk9Xl-Uhtdv9WlxMgNZeSrSt9ySKCtREeCxYEBI1qwrnAy4a4zZMaXAevtiXx41T7IQGu3QV2oq_4etvssMPhokSYkRAhk_nSz9dcThH2u8w-NXZl3av-rS9eiGaVxQvqqmRG79F1iw-fu5frOirJSLEofvc9nlGGZOEMk53tC0siRuP8rJOqaBJsOuPWN5widmNlirKuMjkXTVShAaw-j03zMS4L39P3iuY-d9zLZUpyP3zh9poaRGEUKU5UXayGZIk76HcSsZBriPjV_84prhbh93F83XkWSOcWk1uwU_5GLPP2vu0VRxTuU_G4d1a3-aIjxE0T_OuFVSY0Lw5aAH2urUCljxbU8XDhKaOG8fi1-_HwII-5v-zLit83yy3QbOEFQ
Example Requests - Application Authorization
General Guidelines: The application must include the three required values (client_id, client_secret, and grant_type). The client_id and client_secret are obtained from the Intel Cloud Services Platform Portal when you registered your app. (The portal also uses the term API Key for Client ID; these are the same thing.) For application authorization, the grant_type parameter is hard-coded to "client_credentials". (This parameter may have options in the future, but is constant for now.) Some services may have additional unique parameters.
Note: The base URL for all calls in this document points to the Test environment (:8081 in the path). You need to change the base URL when you move your app to Production.
Commerce Services Example: The call below requests application authorization for Commerce Services. The desired response format is specified in the Accept header as JSON. (The default is XML.)
GET
https://api.intel.com:8081/oauth20/token?client_id={client_id}&client_secret={client_secret}&grant_type=client_credentials
Header:
Accept: application/json
The API Management layer authorizes the app and returns an application authorization token for use in all subsequent calls for the current session. The token is an OAuth bearer token with an expiration of 90 minutes (5399 seconds). The refresh token is used after expiration of the original access token to request a new access token (with grant_type="refresh_token"). The app is responsible for catching access token expiration and handling the refresh request. The app should delete all tokens when a user logs out of the app.
JSON Response
{
"OAuth20": {
"access_token": {
"token": "dadc045f68956c203ce3e43511e71b5d",
"refresh_token": "2896e70c1a9325340e0047fc5e0c8746",
"token_type": "bearer",
"expires_in": 5399
}
}
}
Subsequent calls are made to the specific services URI for the desired Commerce Services resource (see Reference Information below for the base URI for Commerce Services). See the Intel Cloud Services Platform Commerce Services REST Developer's Guide for information on using Commerce Services.
Here's how the same response would look in XML.
XML Response
<OAuth20>
<access_token>
<token>dadc045f68956c203ce3e43511e71b5d</token>
<refresh_token>2896e70c1a9325340e0047fc5e0c8746</refresh_token>
<token_type>bearer</token_type>
<expires_in>5399</expires_in>
</access_token>
</OAuth20>
Code Example - Application Authorization
The following code example shows how to initiate a Location Based Services session with application authorization in JavaScript*. The example uses JQuery and Ajax.
/* Auth to get application authorization access_token for subsequent API calls */
this.LBS_Auth = function()
{
$("#response_text").html("");
document.getElementById('status_text').value = "Auth to get access token...";
var target = tokenUrl + "?client_id=" + client_id + "&grant_type=client_credentials&scope=location:basic" + "&client_secret=" + client_secret;
this.AjaxMsg(target, 'GET', 'jsonp', this.LBS_AuthSuccessP);
}
/* Callback function when Auth succeeds */
this.LBS_AuthSuccessP = function(data, textstatus)
{
access_token = data.OAuth20.access_token.token;
$("#response_text").html($.toJSON(data));
document.getElementById('status_text').value = "Auth succeeds";
}
The following example shows how to use the refresh token to get a new access token (after an existing access token has expired). The example uses JQuery and Ajax.
/* Refresh Auth to get a new application authorization access_token */
this.LBS_Refresh_Auth = function()
{
$("#response_text").html("");
document.getElementById('status_text').value = "Refresh Auth to get access token...";
var target = tokenUrl + "?client_id=" + client_id + "&grant_type=refresh_token" + "&refresh_token="+ refresh_token + "&client_secret=" + client_secret;
this.AjaxMsg(target, 'GET', 'jsonp', this.LBS_RefreshAuthSuccessP);
}
/* Callback function when Refresh Auth succeeds */
this.LBS_RefreshAuthSuccessP = function(data, textstatus)
{
access_token = data.OAuth20.access_token.token;
$("#response_text").html($.toJSON(data));
document.getElementById('status_text').value = "Refresh Auth succeeds";
}
User Authorization
User authorization involves a known user who approves sharing their identity information with the app. This is done using Intel Identity Services and user interaction (via UI screens). The general flow for successful authorization is listed below and shown in the figure that follows:
- The app places the initial HTTP call to Intel Identity Services.
- Intel Identity Services display a UI screen in the device's browser for the user to log into their account.
- The user logs into their account. (They may do this via an Intel Identity Services account or an existing supported social media account.)
- Intel Identity Services display a second UI screen in the device's browser for the user to authorize sharing information with the app.
- The user approves sharing their information.
- Intel Identity Services provide an authorization code back to the app. (This can be done via a synchronous or asynchronous approach; see the Intel Cloud Services Platform Identity Services REST Developer's Guide for details.)
- The app places a second HTTP call to Intel Identity Services, with the authorization code as a parameter to request an access token.
- Intel Identity Services provide a user authorization token to the app for use in subsequent calls.
Intel Identity Services allow users to control the sharing of their identity information with apps that use Intel Cloud Services Platform. Users must establish an Intel Identity Services account. This can be done directly with Intel Identity Services or via a supported third-party identity provider such as Yahoo!, Google, or Facebook. Users then give permission to share their information with apps to take full advantage of the extended capabilities associated with user authorization (previously discussed). For more information on Intel Identity Services, refer to the Intel Cloud Services Platform Identity Services REST Developer's Guide.
Example Request - User Authorization
Context Services: The following discussion follows authorization for Context Services. Your app starts by authorizing with Intel Identity Services (step 1 above). (In reality, the API Management layer performs a basic syntax check on the call, then passes the call parameters to the Intel Identity Services.)
The following HTTP call requests user authorization to the Context Services. The URI includes: (1) a redirect URI for Intel Identity Services, (2) a scope, (3) a state ID, (4) a response type, and (5) an auto register state. The Accept header requests JSON as the response format. These parameters are described in the Intel Cloud Services Platform Identity Services REST Developer's Guide.
POST
https://api.intel.com:8081/identityui/v2/auth?client_id={client_id}&client_secret={client_secret}&redirect_uri=urn:intel:identity:oauth:oob:async&scope=user:details&state=1348510114525&response_type=code&auto_register=false
Header:
Accept: application/json
Steps 2-5 from the authorization flow are accomplished via interaction with the user; these steps are managed on the client side by the browser running on the target device/system. In these steps, the user logs into their Intel Identity Services account and approves sharing information with the app.
Once these steps are completed successfully, Intel Identity Services generate an authorization code for the app. Apps obtain this authorization code using a synchronous or asynchronous approach (step 6 above). The code example that follows this description uses an asynchronous approach. (For information on using a synchronous approach, refer to the Intel Cloud Services Platform Identity Services REST Developer's Guide.)
Once the app has received the authorization code from Intel Identity Services, the app makes a second HTTP call. (Once again, the API Management layer performs a basic syntax check on the call, then passes the call parameters to the Intel Identity Services.)
The following HTTP command requests a Context Services session and includes the authorization code provided by Intel Identity Services. The URI includes: (1) a redirect URI for Intel Identity Services, (2) a grant type, and (3) the authorization code. The Accept header requests JSON as the response format.
POST
https://api.intel.com:8081/identityui/v2/auth?client_id={client_id}&client_secret={client_secret}&redirect_uri=urn:intel:identity:oauth:oob:async&grant_type=authorization_code&code={auth_code}
Header:
Accept: application/json
JSON response for a successful authorization is as follows:
{
"access_token":"{access_token}",
"token_type":"bearer",
"expires_in":"5399",
"refresh_token":"{refresh_token}",
"scope":"user:details"
}
Intel Identity Services authorizes the app and returns a user authorization token for use in all subsequent calls for the current session. The token is an OAuth bearer token with an expiration of 90 minutes (5399 seconds). The refresh token can be used to obtain a new access token if the current session expires. The app is responsible for catching token expiration and handling the refresh request. For refresh requests, however, "grant_type=" must be set to "refresh_token" and a refresh token must be included instead of an authorization code.
Code Example - User Authorization
The following JavaScript code example shows how to request a session for Context Services with user authorization. This example uses an asynchronous approach to obtain the authorization code from Intel Identity Services. (For information on the synchronous approach, see the Intel Cloud Services Platform Identity Services REST Developer's Guide.) The example illustrates initial app authorization.The example uses JQuery and Ajax.
//
// user authorization authorization has 3 steps.
//
// First call services to log the user in and create an authorization code
//
function AuthRequest(DocToModify) {
id = BuildRequestid();
var scopes = 'user:details+user:scope+profile:basic+profile:full+
profile:extended+profile:full:write+user:basic+location:basic+billing:confirm';
var AuthRequestURL = BaseURL + '/identityui/v2/auth?client_id=' + APIKey +
'&redirect_uri=' + RedirectUri + '&scope=' + scopes + '&state=' + id + '&response_type=code&auto_register=false';
WindowRef = window.open(AuthRequestURL);
WindowRef.focus(); // set focus to window
document.getElementById(DocToModify).value = "Auth Request Complete";
}
//
// Second get the created authorization code
//
function GetAuthCode(DocToModify) {
jQuery.support.cors = true;
var URL = BaseURL + '/identity/v2/authcode';
var PostData = 'state=' + id + '&client_id=' + APIKey;
document.getElementById(DocToModify).value = "In Progress";
$.ajax({ url: URL,
type: "POST",
data: PostData,
dataType: "json",
beforeSend: function (request) {
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
},
success: function (data, textStatus, jqxhr) {
document.getElementById(DocToModify).value = jqxhr.responseText;
AuthCode = data;
},
error: function (jqxhr, textStatus, errorThrown) {
alert("auth code An error occurred: " + jqxhr.status + " " + textStatus + "-" + errorThrown);
document.getElementById(DocToModify).value = jqxhr.responseText;
},
});
}
//
// Third get a User Authorization Access Token
//
function GetAccessToken(DocToModify) {
jQuery.support.cors = true;
if (typeof AuthCode == 'undefined') {
document.getElementById(DocToModify).value = 'Request Auth Code first';
return;
}
document.getElementById(DocToModify).value = "In Progress";
var URL = BaseURL + '/identity/v2/token';
var PostData = 'grant_type=authorization_code&code=' + AuthCode.code +
'&redirect_uri=' + RedirectUri + '&client_id=' + APIKey + '&client_secret=' + SecretKey;
$.ajax({ url: URL,
type: "POST",
data: PostData,
dataType: "json",
beforeSend: function (request) {
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
},
success: function (data, textStatus, jqxhr) {
AccessToken = data.access_token;
RefreshToken = data.refresh_token;
document.getElementById(DocToModify).value = jqxhr.responseText;
},
error: function (jqxhr, textStatus, errorThrown) {
delete AuthCode;
alert("An error occurred access: " + jqxhr.status + " " + textStatus + " " + errorThrown);
document.getElementById(DocToModify).value = jqxhr.responseText;
},
});
document.getElementById(DocToModify).value = "In Progress";
}
The following example shows how to use the refresh token to get a new access token after an existing access token has expired. The example uses JQuery and Ajax.
function RefreshAccessToken(DocToModify) {
jQuery.support.cors = true;
if (typeof RefreshToken == 'undefined') {
document.getElementById(DocToModify).value = 'Request Access Token First';
return;
}
document.getElementById(DocToModify).value = "In Progress";
var URL = BaseURL + '/identity/v2/token';
var PostData = 'grant_type=refresh_token&refresh_token=' + RefreshToken + '&client_id=' +
APIKey + '&client_secret=' + SecretKey;
$.ajax({ url: URL,
type: "POST",
data: PostData,
dataType: "json",
beforeSend: function (request) {
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
},
success: function (data, textStatus, jqxhr) {
AccessToken = data.access_token;
document.getElementById(DocToModify).value = jqxhr.responseText;
},
error: function (jqxhr, textStatus, errorThrown) {
delete AuthCode;
alert("An error occurred access: " + jqxhr.status + " " + textStatus + " " + errorThrown);
document.getElementById(DocToModify).value = jqxhr.responseText;
},
});
document.getElementById(DocToModify).value = "In Progress";
}
Reference Information
The following tables summarize parameters used for authorization.
Input Parameters for Application Authorization
| Parameters | Required? | Input Type | Description |
|---|---|---|---|
| client_id | Yes | URI | Unique client ID for the application. Obtained when registering an app with the Intel Cloud Services Platform portal. (Also called APIkey on the portal.) |
| client_secret | Yes | URI | Unique client secret for the application. Obtained when registering an app with the Intel Cloud Services Platform portal. Authorization calls that include client_secret should be POSTs to better protect the information communicated. |
| grant_type | Yes | URI | Grant type. Must be hard coded to "client_credentials" for application authorization requests. |
| scope | Yes | URI | For Location Based Services, this is "scope=location:basic". |
| language1 | No | URI | Location Based Services Parameter: Primary language for Location Based Services (e.g., en=English). English is the default if this parameter is not used. |
| language2 | No | URI | Location Based Services Parameter: Secondary (i.e., fallback) language for the Location Based Services if the primary language is not supported (e.g., fr=French). English is the default if this parameter is not used. |
| application/response | Yes for JSON, optional for XML | Accept header | Response format: JSON or XML. XML is the default if this parameter is not included. Note that this parameter applies during authorization calls only. Response formats for specific services are handled in the respective services calls or by the services default. |
Input Parameters for User Authorization
The descriptions below are summaries to help you get started. Detailed information is provided in the Intel Cloud Services Platform Intel Identity Services REST API Reference.
| Parameters | Required? | Input Type | Description |
|---|---|---|---|
| client_id | Yes | URI | Unique client ID for the application. Obtained from the Intel Cloud Services Platform portal. |
| client_secret | Yes | URI | Unique client secret for the application. Obtained from the Intel Cloud Services Platform portal. Authorization calls that include client_secret should be POSTs to better protect the information communicated. |
| redirect_uri | Yes | URI | The URI where the user-agent will be redirected after the authorization process is completed. Configured in the Intel Cloud Services Platform portal. |
| state | Yes | URI | A random string defined by the application. The same state string must be used for future Intel Identity Services calls during the same session. |
| scope | Yes for authorization code request. | URI | For user authorization, this request includes scopes such as "user:details", "profile:basic", "billing:confirm", etc. depending on which Intel Identity Services profile (basic or full) the app is requesting to access. |
| response_type | Yes for authorization code request. | URI | Must specify "code" as the response type. |
| auto_register | Yes for authorization code request. | URI | Must be "false" for this case. |
| grant_type | Yes for access token request. | URI | Grant type. Must be set to "authorization_code" (and the authorization code must be provided) for initial authorization access token requests. Must be set to "refresh_token" (and the refresh token must be provided) for refresh requests. |
| code | Yes for initial authorization access token request. | URI | Must include authorization code received from Intel Identity Services. |
| refresh_token | Yes for refresh request | URI | Must include refresh token received during initial authorization. |
| language1 | No | URI | Location Based Services parameter: Primary language for Location Based Services (e.g., en=English). English is the default if this parameter is not used. |
| language2 | No | URI | Location Based Services parameter: Secondary (i.e., fallback) language for the Location Based Services if the primary language is not supported (e.g., fr=French). English is the default if this parameter is not used. |
| application/response | Yes for JSON, optional for XML | Accept header | Response format: JSON or XML. XML is the default if this parameter is not included. Note that this parameter applies during authorization calls only. Response formats for specific services are handled in the respective services calls or by the services default. |
Notes
- Language parameters for Location Based Services are not currently applied during user authorization authorization. See the Location Based Services documents for information on setting the languages.
- The following table lists root URIs for the REST services.
Supported Production Services and Root URIs
| Service | Root URI |
|---|---|
| Identity | https://api.intel.com/identity/v2 https://api.intel.com/profiles/v2 https://api.intel.com/identityui/v2 |
| Location | https://api.intel.com/location/v2 |
| Commerce | https://api.intel.com/commerce/v1 |
| Context | https://api.intel.com/context/v1 |
| Catalog | https://api.intel.com/catalog/v1 |
| Curation | https://api.intel.com/curation/v1 |
Error Handling
When errors are detected during authorization, the error information is returned in the body of the response as shown below.
XML
<?xml version="1.0" encoding="utf-8"?>
<error>
<code>API-10005</code>
<requestid>40e972e3:13e5bb9554e:-7980</requestid>
<message>Apikey Invalid</message>
</error>
JSON
{
"error": {
"code": "API-10005",
"requestid": "40e972e3:13e5bb9554e:-7980",
"message": "Apikey Invalid"
}
}
Service codes with the "API-" prefix are generated by the API Management layer. (Other services code prefixes the specific services that generated the error response: "LOC-" for Location Based Services, "CON-" for Context Services, and "CMR-" for Commerce Services.)
The following table is a list of the services codes returned by the API Management layer REST interface.
| HTTP Code | Service Code | Message | Description |
|---|---|---|---|
| 400 | API-10000 | Token not specified | Token is missing from the call. Calls must include an access_token. |
| 400 | API-10001 | Unauthorized | Application is not authorized for specified services. Make sure the client ID and client secret are valid. |
| 400 | API-10002 | (actual error message returned from location services) | Message from underlying Location Based Services. See Intel Cloud Services Platform Location Based Services REST API Reference for more information. |
| 400 | API-10003 | URL transformation error | Client ID is missing or invalid in the static map call (Location Based Services specific). |
| 400 | API-10004 | API Key not specified | Client ID is missing from the call to get an access_token. Ex: /oauth20/token?client_secret=asdasd&grant_type=client-credentials. |
| 400 | API-10005 | API Key not valid | Client ID is invalid in a call to get an access_token. Ex: /oauth20/token?client_secret=asdasd&grant_type=client-credentials&client_id-asd12312~~~. |
| 400 | API-10006 | Tmindex transformation error | Internal API Management layer error. Try the operation again. If the result is the same, contact technical support. |
| 400 | API-10007 | XML to Json transformation error | Internal API Management layer error. Try the operation again. If the result is the same, contact technical support. |
| 400 | API-10008 | JsonP Transformation Error | Internal API Management layer error. Try the operation again. If the result is the same, contact technical support. |
| 400 | API-10009 | No Instance Data | The call requires data, but the data is missing. Make sure the call is providing the proper data. |
| 400 | API-10010 | No User ID | Internal API Management layer error. The access_token is bad, or the scope is not properly specified, or the Intel Identity Services is unavailable. |
| 400 | API-10011 | Token Expired | The access_token has expired. Obtain a new token using the refresh token or via a new authorization. |
| 400 | API-10012 | Invalid Environment | Wrong access_token used. For example, an access_token that is valid for the development environment is being used in a production environment call attempt. |
| 400 | API-10013 | Invalid Subscription | The application has not subscribed to the call. |
| 400 | API-10014 | Operation Not Allowed | The call is attempting an illegal operation. Consult the API Reference for the specific services to determine what operations are supported. |
| 400 | API-10100 | Internal Error | Internal API Management layer error. Try the operation again. If the result is the same, contact technical support. |