Authentication and Authorization

    Access to web APIs in ServiceChannel is implemented by using the OAuth 2.0 authorization code grant flow or an resource owner password flow. The details of each flow are specified in Sections 4.1 and 4.3 of the OAuth 2.0 RFC document, respectively. In this tutorial we will discuss steps needed to authorize using either of the flows, making sure to point out the flow difference as we go along.

    1. Register your application

    To begin, your application needs to be registered in SC api access management portal, using the following URLs:

    You would be able to do it yourself if you have 'SuperAdmin' or 'Provider Power User' rights. If you don't, please ask you SC representative. Registering your apps will provide you with 'Client ID' and 'Client Secret' that you will be able to use for authorizing your application in later steps.

    2. Authorization Grant Flow

    2.1 Requesting an authorization code

    Next, your application should authenticate against ServiceChannel and receive authorization code back. To request an authorization code, the following request should be issued:

     

    Where parameters are as follows:

    response_type

    always 'code'

    client_id

    Client ID received during the registration process

    redirect_URL

    Escaped redirection URL of your application(Called Callback in registration)

     

    A typical session example might look like this:

    Typical Session

     

    This will open up the request form for the user to login if it’s not logged in already. After successful login, authorization code will be returned back to the return URL:

    Authorization Code Return URL

    2.2. Access token request

    After application receives an authorization code, it can be redeemed to get an access token. In order to do it, send an HTTP POST request to ServiceChannel authorization endpoint:

     

    Where body parameters are as follows:

    grant_type

    always 'authorization_code'

    redirect_URL

    Redirection URL of your application

    code

    Authorization code received at the previous step

     

    Authentication here should happen using client_id and client_secret as username and password in a ‘Basic’ authentication.

    Continuing the previous example it will look like this:

    Authentication Example

    Authentication Example

    3. Resource Owner Password Flow

    3.1 : Request an access token

    In this flow client is able to request an access token directly as a result of an authorization request.

    In order to do it, send an HTTP POST request to ServiceChannel authorization endpoint:

     

    Where parameters are as follows:

    grant_type

    always 'password'

    username

    Resource owner username

    password

    Resource owner user password

    redirect_URL

    Redirection URL of your application

     

    Authentication here should happen using client_id and client_secret as username and password in a Basic authentication.

    4. Using the access token to access the resource

    After you have received an access token you can use it to access the resource by supplying it in the with the Bearer authorization header:

    5. Using a refresh token to access a new token

    When an access token expires, the native client application can use the refresh token to get a new access token. The lifetime of a token is 600 seconds. In order to request a new access token, one should use the following end point:

    Where body parameters are as follows:

    grant_type

    always ‘refresh_token'

    refresh_token

    The refresh token that was included in the response that provided the access token.

     

    Authentication here should happen using client_id and client_secret as username and password in a Basic authentication.

    A typical access token response would look like:

    Authentication Example