API Authentication Token
By the end of this tutorial you should understand:
• What an API authentication token is and why it is required.
• What a "grant type" is and when to use each type in your applications.
OAuth2 Authentication Overview
To use any of the inContact APIs, you must have a current and valid API Authentication Token. Tokens are generated by the inContact Token Service which is an OAuth 2.0-based service, and follows the OAuth 2.0 specification.
In the current version of the inContact API Framework, only the Implicit, Password, and Client "grant types" are fully implemented. Support for the Authorization Code grant type will be added in a future release.
Each OAuth grant type is designed for optimal security and usability for applications based on how that application is used and what access it requires in the inContact system. You must decide which token grant type you will use in your application based on the following recommendations:
• Implicit: If your application is a web-server-based application, or a browser-based application,
and if it needs access to resources on behalf of a specific user, you should use the Implicit grant type. A good example of this
type of application is when you install a 3rd party extension to a software application that needs to request permission from the user
for access from the user account in the software application. Implicit tokens are valid for 60 days and do not include a refresh token.
• Password: If your application is server-based (but not running on a web server), or desktop-based (but not running in a browser), or a native mobile application, and if it needs access to resources on behalf of a specific user, you should use the Password grant type. Password tokens are valid for 3600 seconds and include a refresh token that is valid for 7200 seconds.
• Client: If your application does not need access to inContact resources that are not owned by a specific user, regardless of whether it is server-based, browser-based, desktop-based, or mobile, you should use the Client grant type. Client tokens are valid for 3600 seconds and do not include a refresh token.
When your application browses to the inContact web site, it also sends a "requested redirect URI" where the inContact web site will redirect the user after they successfully authenticate. The requested redirect URI must match one of the redirect URI’s you specify when you register the API Application with inContact (see the getting started tutorial). The API Authentication Token is sent by inContact to the redirect URI (which also makes it available to the browser-based application).
Your application can use this token directly to make API calls. The token identifies the application, the vendor, and the authenticated user. Any API calls made with the token will be limited by the user’s permissions within inContact, and also by the scope of the application, as configured in the app registration.
Password tokens are best used for non-web applications that run on the desktop, on a server, or on a mobile device. The user credentials used to create a password token are either known by the application, or provided to the application by the user.
Your application uses the username and password to request and receive an API Authentication Token directly from the inContact authorization server. Password tokens contain information about the authenticated user. The user is authenticated by sending the user name and password along with the token request. If the user name and password are valid, a token is granted.
The token identifies the application, the vendor, and the user. Any API calls made with the token will be limited by the user’s permissions within inContact, and also by the limited scope of the application, as configured in the app registration.
Implicit and Password tokens are required when making API calls that require a "user context". For example, retrieving a list of agents from the platform requires a user context, and the API call will fail if the user specified does not have the required permissions (even if the user name and password are valid).
Client tokens are used in browser-based, server-based, desktop-based, and mobile applications that do not need to identify a specific user. You do not send user name and password information with client token requests.
Client tokens are useful for API calls that do not require a user context. For example, if you are creating a web page that allows a patron ("caller") to request a web chat with an agent, you would use the "Start Chat" API call. This call does not require a user context, since the patron making the request is not a user in the inContact system.
NOTE: As a best security practice you should use the Client token whenever you are calling an API from a publically available website outside of your domain control. Although you can call any API method with the Implicit or Password token, using a Client token is more secure, since it is limited to the Patron scope and requires no user authentication information such as credentials that could be compromised by a rogue or malicious application running in the browser.
Once the application has a token generated by the Token Service, it must send the token with each API call it makes. The token allows the inContact API Framework to identify the application, the application vendor, and the user who is using the application (if applicable).