Getting Started
API Authorization
The ItemExtend API uses two forms of authorization to secure calls and prevent inappropriate access of the API by third parties.
- For anonymous "guest" user support, a simple Application Key is provided,
which should be provided in the
Authorizationheader of any request to the for guest authoriztion, you will be issued your own unique Application Token. - For authenticated user accounts, the OAuth2 standard authorization methods are used. This involves allowing a user to log in to ItemExtend, which will then provide a user-specific Access Token, which can be used to authorize future API calls. For OAuth2 authorization, you will be issued your own application-specific Key and Secret values.
For more detailed information on OAuth2, please see RFC-6749, the official OAuth2 specification
Acquiring a Guest Application Key
We will issue your guest-access application key for your team to work with. Please reach out to your ItemExtend Contact to work on getting this set up.
Using a Guest Application Key
To use your guest application key, simply provide it in the "Authorization" header when making API requests, as follows:
Authorization: token <token value>
Acquiring an OAuth2 Key and Secret
We will issue your Key and Secret values for use with the OAuth2 standard authorization flows. NOTE: It is very import you keep the Secret value confidential. Allowing public access to your Secret may allow unauthorized access to your data.
Selecting an OAuth2 Authoriztion Flow
The OAuth2 specification allows for four different authorization flows, but the two most common flows are the Authorization Code Grant and the Implicit Grant flow. When you speak with an ItemExtend Contact to obtain your OAuth2 Key and Secret, you should indicate which flows you intend to implement, so your Key and Secret can be configured correctly. If your application requires one of the less common authorization flows, speak with your ItemExtend Contact. This article describes the various recommended approaches to OAuth2 flow and the advantages and disadvantages of each.
Using the OAuth2 Key and Secret
The ItemExtend API provides endpoints to support the various OAuth2 authorization flows. Because it utilizes each of these endpoints, the following descriptions and examples will assume you will implement the Authoriztion Code Grant flow.
Endpoints
Authorize
GET /api/o/authorize
Initial authorization endpoint Corresponds to the OAuth2 specified Authorization endpoint
This endpoint accepts all of the parameters as described in the OAuth2 spec.
Any additional parameters are ignored.
In the Authorization Code Grant flow, this endpoint will redirect the user
to a login page if not already logged in, and then redirect back to your
application at the url specified in the redirect_uri parameter.
Token
POST /api/o/token
Token exchange endpoint Corresponds to the OAuth2 specified Token endpoint
This endpoint requires the client application to post the authorization code
received via the authorize endpoint and exchange it for an Access Token,
which can be used to access API calls. In the Authorization Code Grant flow,
this endpoint will also provide a Refresh Token which can be used to get a
new Access Token when that token expires.
Because the Implicit Grant flow provides an access token directly with the
authorize endpoint, this endpoint is not used in that flow.
Revoke Token
POST /api/o/revoke_token
Token revocation endpoint Corresponds to the OAuth2 specified token revocation process
This endpoint allows a user to revoke his own token, or for your application to revoke a token on a user's behalf. It is most commonly used to ensure a user is fully logged out of the system and that someone else who may be using the same computer cannot inadvertently log in as that user. It can also be used to immediately revoke API access to a user whose account has been deactivated. You may revoke both Access Tokens and Refresh Tokens using this endpoint.
postMessage
Ajax Calls
Headers
The current method for unique user tracking is to pass the withCredentials
and your application Authorization token for guests.
For users, pass the Authorization Bearer token, and set withCredentials to
false. In the event your Oauth token has expired, ItemExtend will respond to
a request with a 401 error.You will need to catch this and have your backend
to use the refresh token provided by Itemextend to get a new token.
We are researching the possibility of using a different method for this to allow for Single Page Applications, but at this time, we do not have a solution for this.