Authentication and Authorization

4 minute read

We use the OAuth 2.0 protocol for authentication and authorization. Two grant types are supported: authorization code and resource owner password credentials.

Follow this guide to learn how to authenticate your application and access the ServiceChannel API.

Authorization steps

Note: Check the OAuth 2.0 official portal and OAuth 2.0 Authorization Framework document to learn more about this protocol.

Step 1. Register Your App

Register your application to get client_id, client_secret, and callback URI.
See App Registration for detailed instructions.

Step 2. Encode App Credentials

Encode your application OAuth credentials to securely use them in the next step. Combine your client_id and client_secret, separate them with a colon :, and Base64 encode the combined values.

To encode client_id and client_secret:

  1. Open any base64 encoder, for example, base64encode.org.
  2. Insert client_id:client_secret into the field and click ENCODE. Here is an input example:

      SB.2014917243.70943550-9974-41E7-8B38-CA8C8C024262:1C600CB7-4D24-4787-BB3E-ACD2B2FBF745
    

    Important: Make sure that there are no spaces or other unnecessary symbols in the input field.

  3. Save the encoded string — you will need it in the next step. This is our output example:

      U0IuMjAxNDkxNzI0My43MDk0MzU1MC05OTc0LTQxRTctOEIzOC1DQThDOEMwMjQyNjI6MUM2MDBDQjctNEQyNC00Nzg3LUJCM0UtQUNEMkIyRkJGNzQ1
    

Step 3. Obtain Authorization

Choose between two grant types to obtain authorization:

Resource Owner Password Credentials

Use this grant type when you have the resource owner credentials: username and password for the ServiceChannel account. Exchange these credentials for access_token.

Request access_token

To get access_token, send a POST request:

POST /oauth/token

Header Value Note
Authorization Basic {encoded client_id:client_secret} Replace with your encoded client_id:client_secret
Content-Type application/x-www-form-urlencoded  
Parameter Parameter type Value Note
username Body SC-Dev1 Replace with your username
password Body servicechannel1 Replace with your password
grant_type Body password  

Example request:

POST https://sb2login.servicechannel.com/oauth/token HTTP/1.1
Authorization: Basic U0IuMjAxNDkxNzI0My43MDk0MzU1MC05OTc0LTQxRTctOEIzOC1DQThDOEMwMjQyNjI6MUM2MDBDQjctNEQyNC00Nzg3LUJCM0UtQUNEMkIyRkJGNzQ1
Content-Type: application/x-www-form-urlencoded

username=SC-Dev1&password=servicechannel1&grant_type=password

Example response:

{
  "access_token": "AAEAAI44ctDQrQ007-wz-r0IyNgUCgz1QAaqbYqhmh30LuOfccRds-OLhwVPg4LDm2m4VR_OIoKiqJzOa8BRPb00pYqZikB11pRP71ttkp6oi6urPYwzT09wJKkXkfc6kT1z5888K7TtEhI3WjUF-rg_LLhQSDswsgfuulDXuKSy6dBVlIdpTf8hxRjiPSPvdJh8djuG-jPTXiss6XIo6RYMi35koX1wSPpRo6xwydpDHLpY6MztSbcjeqoYKmdYk8mP8SpOwQZjZRkdvBre88oyIuIbbtn9Letu-4V4JZygY5vgkrdbXAK7bZnRtUE06i8D9z0XAmOrmpKSlYjcaSnY1wv0AQAAAAEAAAJLJPJwWr7YwN7yv6LkOAydQqsfYFta5wFgcFZR0P8qXXGIHp6lt3HFVmGFXWeXOR_6ny6jPaKxop9uEyCl_v2pYWdLebcOaS1KZhpJVqA-b17e3ZFwKTtr3fdXw2mPo5NYsQCRPPGpxphCjcQI_bsidXHsZpiVdYGtQrVdkcZcDxoN1mkwzKWnrjsFPFHKIU251AUmRZYgLcjKhAqYy-0E7Gg5mKwcHL0D2_UUie4om1CHaLBiyHQnVWbSZ5ccjllh2SWxtuiuQI4IM0z_8IuZrVKh3KarMjBeSGsWAKELnGUvoZUahPq5tsQrdph8U1gAhyeoJg3HshXlXI3szX-0bMXqm0r4px4Hz58xSDR6W_SPnbefZwp_lD-dUlDewbdaOMGY32zgZlpz8dF3zOkTkdOQShpDjO_egktdj_zX0k9VH1N_TgGfZWtb_40ihvvydDncycwvieITRc3r29mxjdo65bPl0diJYMhKRVnr-hd9ZBQQtEdBwvMPq0hNbokXaIsFy9tyy5v7f-O4ozulAcjTcbzeU1K6zbPX5HPIvfb3YtyqOGDDp-YbiH7bHkZlM6_s56zXEJKF0h37VR66lBuFHcRwe1coaSjI2-REv4PqqFYd5qrOocyhwvAlJrY8gU5LWBAIISC0aTE5pl8",
  "token_type": "bearer",
  "expires_in": 600,
  "refresh_token": "gDoX!IAAAABzoOUZoBUUClEEOpCf3xYKU55aGu3FaKPg5hxqkwPTN0QAAAAF73mjZxMcbK5vEoV0NxWzyvZf360UzacuRN-J5KWmL6gQYVwwMy6xR7bzMGm7AbNJtL52ydc2vKXIj3D5dqILIHFZfoI0igTlvwkYtvChkCAh-ocRRGqTVb2n2KKvhUFTZnrTInMG5K313YPdPP21yPUJIF442VabkkRrADN2X6rrlZGIe9vKtJfUnnJdMRs-TvsGQLBulBNx5FxvFlj1sWB92wE2L-ns_OKyMDT0p0f3EoBVsH2rgtrSiX7JVgGAFoCUA3LZO_y-fGE4deLJq"
}

Response code: HTTP/1.1 200 OK

The response body contains access_token that you need to authorize calls to the ServiceChannel API.

Authorization Code

You can use this grant type even when you do not have the resource owner credentials (username and password for the ServiceChannel account).

With the authorization code grant type, the resource owner is redirected to the authorization server, signs in using ServiceChannel credentials, and is redirected to your app callback URI.

The URI contains authorization_code that you exchange for access_token.

Request authorization_code

To obtain authorization_code, send a GET request to the authorization endpoint. You can use your browser address bar to issue this request but omit the GET verb.

GET /oauth/authorize

Parameter Parameter type Value Note
redirect_uri Query https://sb2api.servicechannel.com/swagger/ui/o2c-html Replace with your callback URI. Omit this parameter when your app has no callback URI.
client_id Query SB.2014917243.70943550-9974-41E7-8B38-CA8C8C024262 Replace with your client_id
response_type Query code  

Example request:

GET https://sb2login.servicechannel.com/oauth/authorize?response_type=code&client_id=SB.2014917243.70943550-9974-41E7-8B38-CA8C8C024262&redirect_uri=https://sb2api.servicechannel.com/swagger/ui/o2c-html

If you are not logged in, a login form appears. Either you or the resource owner should enter the SC credentials. If you are already logged in, you get a response URL immediately.

Response URL:

https://sb2api.servicechannel.com/swagger/ui/o2c-html?code=Lb2H%21IAAAAA-4jDlLGC_GkcYuc-oF61TQEeTYfrAqJgCJJnUX0hOpEQEAAAHqhLXHbUVvfJL6F6CQW7NrQ_BKwRuMg0F6ps_UWukICIwLWEieo4rEyqOwQ3gnKwsmQR31XId4BNqLuIZaZyJH1e_T1PITXGUnXFsWrvfpK1Ie6PNdSZ3gI6f8Ekmw9MHudKdnrHN_Cjpcx6TcIJiMoWXg6bq4NZsRtQsBdwBcJka65HEq4v0KBzdP4BBZbSh2H774QEj55hEuMAhQ3aCfCy1chLRIk768oA6QNXnSB3qMTZFA6jv7jus1x6riK6oICAr2Y4gVi6M5sSEBrPsFtKwi7HkP9jHEk4US_7fo5nA0m8PTKkCkm2FQW8TwSv4G69OYSN-xyTI_mAxRFTKcBNHWAr7wN5bfPud_4X3rQQ

In the response URL, the code key value is authorization_code. Exchange it for access_token in the next step.

Request access_token

To get access_token, send a POST request to the token endpoint:

POST /oauth/token

Header Value Note
Authorization Basic {encoded client_id:client_secret} Replace with your encoded client_id:client_secret
Content-Type application/x-www-form-urlencoded  
Parameter Parameter type Value Note
code Body {authorization_code} Replace with your authorization_code
redirect_uri Body https://sb2api.servicechannel.com/swagger/ui/o2c-html Replace with your callback URI. redirect_uri is required when included in the authorization request described above.
grant_type Body authorization_code  

Example request:

POST https://sb2login.servicechannel.com/oauth/token HTTP/1.1
Authorization: Basic U0IuMjAxNDkxNzI0My43MDk0MzU1MC05OTc0LTQxRTctOEIzOC1DQThDOEMwMjQyNjI6MUM2MDBDQjctNEQyNC00Nzg3LUJCM0UtQUNEMkIyRkJGNzQ1
Content-Type: application/x-www-form-urlencoded

code=Lb2H%21IAAAAA-4jDlLGC_GkcYuc-oF61TQEeTYfrAqJgCJJnUX0hOpEQEAAAHqhLXHbUVvfJL6F6CQW7NrQ_BKwRuMg0F6ps_UWukICIwLWEieo4rEyqOwQ3gnKwsmQR31XId4BNqLuIZaZyJH1e_T1PITXGUnXFsWrvfpK1Ie6PNdSZ3gI6f8Ekmw9MHudKdnrHN_Cjpcx6TcIJiMoWXg6bq4NZsRtQsBdwBcJka65HEq4v0KBzdP4BBZbSh2H774QEj55hEuMAhQ3aCfCy1chLRIk768oA6QNXnSB3qMTZFA6jv7jus1x6riK6oICAr2Y4gVi6M5sSEBrPsFtKwi7HkP9jHEk4US_7fo5nA0m8PTKkCkm2FQW8TwSv4G69OYSN-xyTI_mAxRFTKcBNHWAr7wN5bfPud_4X3rQQ&redirect_uri=https%3A%2F%2Fsb2api.servicechannel.com%2Fswagger%2Fui%2Fo2c-html&+grant_type=authorization_code

Example response:

{
  "access_token": "AAEAAJgjGpJR6jsG6PTTftfdzAgHWyjk1tHlMByAkGeSkpXbFH2Vn3KcHL1_E4Rb8gzAdjg9h4vw_2DTM4uStcAvrEkqCXG52M_CqmBDoLj-Vf_0CmkBCb7EY_9TOsmkmBGMV5UVpVcY-Y-PcD43ERowTG6kJTkJON1wW7O_HZ2SP2Ytmra19B-xugHjvD5u1cnYNy_6D4dhnGv4or4om7CYkCud1diuWT_Fdn9AJebe59JI76LfIZdgIajxg5A4a3wFmivaXHcfaCwfTsSaMS5CWGl3NiqoDV3O_DxNVjY5Q6PryUYF9rcYt5DVtgJmD10aAy4YMUKrLqhKUqzwhhm_K7n0AQAAAAEAAE03VevSRiUWsasi0DqGf2XTw3H8vv21xkaHR-a8Si88BFxtLUVZ3yEyhPQHHEkiLdZ5DRvouRFZKbwkvHBxoTps9G2Nr37uvxr2Q3dr1YuIZ3DiAd5NQpkC1CYvMCatU6zlvkCHfD30JnaOPsfslYKleDjqgqx4tFJ_6bjes3FlaEp6vzKVwDCjuaGOqoL-oiqvW8jeBMrL2g4kGv-W3Braez7XvIraICe2CU0aov58oEc2-JBebCLTpQY_8tz71qgJvfAXlXyFZk0VM-fXaouO35D2zUoAM5PP8gGlqwWtGM6rVOCPqzBGWXO7lFjQz2nB_QruEDhpBWIjPvR3kFy5BtIK_ywPvDJp3Z4Nt6UcGZYXksO83mEutPuS7YMMzTaieBKR4xgF7xADJc8GpHgRUo8mqpDnE9-IPbflI9EXKjU4p0GXrwMz-0yFfngznppqcZAcvwKn8q6dfo1OrHSENfoBDyyQNM6dryIEJqCiZT5T3f3rkxmsLP6H1ObQg43rB-mheKv_MpKZNQEFd1ebc1-Fdxy1lAiRH_nI7FyaKzcdhdygh76jXWmL2oFD2o7nhLek2Rd498gJ9607ACU4qyH2uulu-bXyKlWkacru1VnRlBudcLNCgjHshIJAOmxutawWF6_ISV75mDZc_rk",
  "token_type": "bearer",
  "expires_in": 600,
  "refresh_token": "3jPA!IAAAAMF2jCy4zdK3l6poWtscY5eTX6FkCo1yh3zHItJwdw1u0QAAAAFA9TDXPBCHjw2QX5T4MmgbiYceT66uDKl_S-ZVIyasVo6DCTCbUjBQlgrpquZtVwSqRjCTJM8ioY9oRd5H5OlcR4s6JgWJGIhBRCQMiLR9dPfUoJgp7EBG7KTeqazV2vtKnUoPdTU-g8m6A7txg3Wq-DpfnTIX83sWViQ32zo6E7FT56x3iU4jDUPL9Ls7Wy7Hx6SM7lg80qhLF8PZOMIqVqt53g9p4UQlj1jZ8rCMBIN_EeHP1jr2ZbU4_SmSekHxtsFmCZnMfjrdjt2T0jbV"
}

Response code: HTTP/1.1 200 OK

The response body contains access_token that you need to access our API.

Step 4. Access Our API

To call our API, you must include the Authorization header with the value
Bearer {access_token} in every API request. Unauthorized calls will fail and result in
401 Unauthorized error.

A sample request to get information on the work order #12345678 might look like:

GET https://sb2api.servicechannel.com/v3/workorders/12345678 HTTP/1.1
Authorization: Bearer AAEAAI44ctDQrQ007-wz-r0IyNgUCgz1QAaqbYqhmh30LuOfccRds-OLhwVPg4LDm2m4VR_OIoKiqJzOa8BRPb00pYqZikB11pRP71ttkp6oi6urPYwzT09wJKkXkfc6kT1z5888K7TtEhI3WjUF-rg_LLhQSDswsgfuulDXuKSy6dBVlIdpTf8hxRjiPSPvdJh8djuG-jPTXiss6XIo6RYMi35koX1wSPpRo6xwydpDHLpY6MztSbcjeqoYKmdYk8mP8SpOwQZjZRkdvBre88oyIuIbbtn9Letu-4V4JZygY5vgkrdbXAK7bZnRtUE06i8D9z0XAmOrmpKSlYjcaSnY1wv0AQAAAAEAAAJLJPJwWr7YwN7yv6LkOAydQqsfYFta5wFgcFZR0P8qXXGIHp6lt3HFVmGFXWeXOR_6ny6jPaKxop9uEyCl_v2pYWdLebcOaS1KZhpJVqA-b17e3ZFwKTtr3fdXw2mPo5NYsQCRPPGpxphCjcQI_bsidXHsZpiVdYGtQrVdkcZcDxoN1mkwzKWnrjsFPFHKIU251AUmRZYgLcjKhAqYy-0E7Gg5mKwcHL0D2_UUie4om1CHaLBiyHQnVWbSZ5ccjllh2SWxtuiuQI4IM0z_8IuZrVKh3KarMjBeSGsWAKELnGUvoZUahPq5tsQrdph8U1gAhyeoJg3HshXlXI3szX-0bMXqm0r4px4Hz58xSDR6W_SPnbefZwp_lD-dUlDewbdaOMGY32zgZlpz8dF3zOkTkdOQShpDjO_egktdj_zX0k9VH1N_TgGfZWtb_40ihvvydDncycwvieITRc3r29mxjdo65bPl0diJYMhKRVnr-hd9ZBQQtEdBwvMPq0hNbokXaIsFy9tyy5v7f-O4ozulAcjTcbzeU1K6zbPX5HPIvfb3YtyqOGDDp-YbiH7bHkZlM6_s56zXEJKF0h37VR66lBuFHcRwe1coaSjI2-REv4PqqFYd5qrOocyhwvAlJrY8gU5LWBAIISC0aTE5pl8

Step 5. Regenerate an Access Token

All things must pass: your access_token expires after a time period set in the expires_in property of the POST /oauth/token response. The time period is in seconds.

Use refresh_token that you have received with the POST /oauth/token request to generate a new access token.

POST /oauth/token

Header Value Note
Authorization Basic {encoded client_id:client_secret} Replace with your encoded client_id:client_secret
Content-Type application/x-www-form-urlencoded  
Parameter Parameter type Value Note
refresh_token Body {refresh_token} Replace with your refresh_token
grant_type Body refresh_token  

Example request:

POST https://sb2login.servicechannel.com/oauth/token HTTP/1.1
Authorization: Basic U0IuMjAxNDkxNzI0My43MDk0MzU1MC05OTc0LTQxRTctOEIzOC1DQThDOEMwMjQyNjI6MUM2MDBDQjctNEQyNC00Nzg3LUJCM0UtQUNEMkIyRkJGNzQ1
Content-Type: application/x-www-form-urlencoded

refresh_token=gDoX!IAAAABzoOUZoBUUClEEOpCf3xYKU55aGu3FaKPg5hxqkwPTN0QAAAAF73mjZxMcbK5vEoV0NxWzyvZf360UzacuRN-J5KWmL6gQYVwwMy6xR7bzMGm7AbNJtL52ydc2vKXIj3D5dqILIHFZfoI0igTlvwkYtvChkCAh-ocRRGqTVb2n2KKvhUFTZnrTInMG5K313YPdPP21yPUJIF442VabkkRrADN2X6rrlZGIe9vKtJfUnnJdMRs-TvsGQLBulBNx5FxvFlj1sWB92wE2L-ns_OKyMDT0p0f3EoBVsH2rgtrSiX7JVgGAFoCUA3LZO_y-fGE4deLJq&grant_type=refresh_token

Example response:

{
  "access_token": "AAEAAHvK-kwaKbCqmYDQHuO19TZe9NQShKmJG-qnbaHKrfDFcmP16QovG7h_OFi8MIcRukRtnk7tHnvj-7GQcTuBMKalJ9FDg7jIin2VHtSvyXuw776LZwTNjjkUsPK2QLoYycifItymdSeCdA8TwBL9VGN9UvRt2gIG2UG-jngEfOjOkcEPR9tKIL_1DxO3atUEYkkCTRG7zF-VdogR65O0QI2Jct5ITx08YOnKKCujxSo0nXwbeE3WeGXDi4ihcNuJBIyFR144-n5i7RuRNtppDZ3gC_IUJgt4t9iVMW8yDBZJq_wpZPQ7vc8OLLuQwVrFtfkQpFBVJPDoPXOZtHTuvij0AQAAAAEAABx1d35baq8RalnPYAzQ3vcRX7wMCelLNgXpwvUOMNqxzIWP5cxqjK2n58OAq1EDc9OuazT66qmZGpVg5bLLFRi1MI3lp0yCuruxyJznTG97syB_F23nQRgBwYZB9l6DX3dzlG_H2dWB7lEZ7reNTEq2TuFZBsyTlHoY3_1WEqE8mRWWgM3muZV6raEbSkXc0SDTFdAhTK5lPpnKuN30YFbrKtBrnPMsElCVBgBzz7rhABKK6IVNpHVEQCrKf7i5QHN2Ax__g4QcJF9ywx4ccLSFs2zyvODjUzjoJjW5QrW6Bc9VUXmUA39Eu_5O6OKUHAsdnnN72AF8K_xH6YLrjeCiyh4bHlio2ALUS1ksuY9ZHqH63j47JOk24L5L4CWQFhTl4pUlPGiudVHCwQGrUCvLiuxyOzJqrqdNbdG3e1tE1QxwqU4Dd4pCsU-CC6Fks-ETGR18gCqYjjTZBdYy4SKnqeAdfc7mmx7J3jwwW1F2oLHwgE0Er6bkxneLSG0nko9ZAERSZSQfsDR3a67pUvqFiWV58p0n6v4yfUrBuBvFu0uoOZCqP4CvaAXKXw1ux_1St3gQffscFWRv1rJc4eWpeKq7j_WeVWNdejR6L_9FLSGJ2M5Eop9P1g1wBrpZ--fiJo0foC3ewZ_PIGGGchU",
  "token_type": "bearer",
  "expires_in": 600,
  "refresh_token": "3jPA!IAAAAHuPywUyJIaMixVP4uspyXD366mBM5LP1HeqNpKVjMGS0QAAAAFFQXPuyfdaP6X3SOefZpabP6_NhBN59w7lbYNTbixVH7MlH-mQ9YaQcwvYe4sdNDvj_PVfOWDHFQvTSR763yPyJJ9KQGfbf1xsbvqcUCja6ewZ1S-LktGqbew2RzwC3LsU88zXRchRgSm6ZG7Jq2s38FNj_5w8ocKCXG0G2pYs08gtj6TusH45uafhpOt4QZjLWpLTXv_nHKD97gBI_7RlPJzxXYln34K5Avb7bBRnlOEzB9pVMoHb8EWy2MiDdzEez5koXYuVP30uzREwXrIY"
}

Response code: HTTP/1.1 200 OK

The response body contains access_token that you need to integrate with our API.