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 NICE inContact APIs, you must have a current and valid API Authentication Token. Tokens are generated by the
NICE inContact Token Service which is an OAuth 2.0-based service, and follows the
OAuth 2.0 specification.
In the current version of the NICE 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 NICE 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 NICE 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.
and that are accessed through a browser. Implicit tokens contain information about a specific user.
The Implicit Token grant process is a two-stage process where the user is directed by your application to a
special NICE inContact authentication web site, where they enter their NICE inContact credentials and then asks them to grant
the requested types of permission needed by the application.
When your application browses to the NICE inContact web site, it also sends a "requested redirect URI"
where the NICE 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
NICE inContact (see the getting started tutorial).
The API Authentication Token is sent by NICE inContact to the redirect URI (which also makes it available to the browser-based
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 NICE 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
NICE 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 NICE 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 NICE 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 NICE inContact API Framework to identify the application, the application vendor,
and the user who is using the application (if applicable).