Authentication

To be allowed to access any part of the nguc-api the user must first authenticate with the api by logging in using a registered user account.

Authentication follows the OAuth 2.0 Password Grant flow.

To authenticate itself the user must send an HTTP post request to: https://api-nguc.weblink.se/oauth2/user-credentials

The request must contain the following information:

grant_type:password
client_id:external.COMPANY_NAME
username:YOUR_USERNAME
password:YOUR_PASSWORD
tfa:EMPTY STRING OR CURRENT 2 FACTOR AUTHENTICATION CODE IF ENABLED FOR USER.

The credential information can be sent as either a json document or as url-encoded form data.

  • grant_type: Must be specified as password .

  • client_id: Must be specified as external.COMPANY_NAME (change COMPANY_NAME to your company name.

  • tfa: If 2 factor authentication is enabled for the user then this parameter must specify the user's current 2 factor authentication code. In case 2FA have not been enabled for the user the value of this parameter must be left empty ie. specified as an empty string.

If authentication is successful the api will return HTTP status code 200 with a json document containing the new access_token information.

if authentication fail due to incorrect password the api will respond with http status code: “401 Unauthorized”.

if authentication fail due to either unspecified, incorrect or an expired 2FA code then tha api will return http status code: “402 Payment Required”.

Example sending credentials as a json document in the request body:
curl --data-raw '{"grant_type":"password","client_id":"external.COMPANY_NAME","username":"YOUR_USERNAME","password":"YOUR_PASSWORD", "tfa":"" }' \
-H 'Content-Type: application/json' \
-X POST https://api-nguc.weblink.se/oauth2/user-credentials
Example sending credentials as url encoded form data:
curl -d 'grant_type=password' \
-d 'username=YOUR_USERNAME' \
-d 'password=YOUR_PASSWORD' \
-d 'tfa=' \
-d 'client_id=external.COMPANY_NAME' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-X POST https://api-nguc.weblink.se/oauth2/user-credentials
Authentication response
{
	"access_token":"NEW_ACCESS_TOKEN",
	"expires_in":86400,
	"token_type":"Bearer",
	"scope":null,
	"refresh_token":"NEW_REFRESH_TOKEN"
}

The returned access_token has limited lifetime and will need to be manually refreshed by the client. To refresh the access_token the user must send a post request to the refresh-token endpoint (/oauth2/refresh-token) and specify the refresh_token that was received in response to the authentication request above. The refresh-token response will contain the new access token aswell as a new refresh_token to use when the new access token expire.

Example refreshing lifetime using a json document
curl --data-raw '{"grant_type":"refresh_token","refresh_token":"CURRENT_REFRESH_TOKEN","client_id":"external.COMPANY_NAME"}' \
-H 'Content-Type: application/json' \
-X POST https://api-nguc.weblink.se/oauth2/refresh-token
Example refreshing lifetime using url encoded form data
curl -d 'grant_type=refresh_token' \
-d 'refresh_token=CURRENT_REFRESH_TOKEN' \
-d 'client_id=external.COMPANY_NAME' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-X POST https://api-nguc.weblink.se/oauth2/refresh-token
Successful response to refresh access_token lifetime.
{
	"access_token":"NEW_ACCESS_TOKEN",
	"expires_in":86400,
	"token_type":"Bearer",
	"scope":null,
	"refresh_token":"NEW_REFRESH_TOKEN"
}

Any further requests sent to the api must be authenticated by adding an HTTP "Authorization" header containing the access_token from the previous step. As in the following example.

Example request listing countries
curl -H 'Authorization: Bearer CURRENT_ACCESS_TOKEN' \
-X GET https://api-nguc.weblink.se/country
Success response listing countries.
[
	{"id":"1","name":"Sweden","pbx_tz_id":"398","country_code":"46"},
	{"id":"2","name":"Great Britain","pbx_tz_id":"378","country_code":"44"},
	{"id":"3","name":"Denmark","pbx_tz_id":"366","country_code":"45"},
	{"id":"4","name":"Finland","pbx_tz_id":"370","country_code":"358"},
	{"id":"5","name":"Norway","pbx_tz_id":"386","country_code":"47"},
	{"id":"6","name":"Estonia","pbx_tz_id":"399","country_code":"372"},
	{"id":"7","name":"Latvia","pbx_tz_id":"390","country_code":"371"},
	{"id":"8","name":"Austria","pbx_tz_id":"398","country_code":"43"},
	{"id":"9","name":"Albania","pbx_tz_id":"400","country_code":"355"},
	{"id":"10","name":"Andorra","pbx_tz_id":"356","country_code":"376"},
	{"id":"11","name":"Armenia","pbx_tz_id":"332","country_code":"374"},
	{"id":"12","name":"Azerbaijan","pbx_tz_id":"263","country_code":"994"},
	{"id":"13","name":"Belarus","pbx_tz_id":"383","country_code":"375"},
	{"id":"14","name":"Belgium","pbx_tz_id":"361","country_code":"32"},
	{"id":"15","name":"Bosnia Herzegovina","pbx_tz_id":"394","country_code":"387"},
	{"id":"16","name":"Bulgaria","pbx_tz_id":"397","country_code":"359"},
	{"id":"17","name":"Croatia","pbx_tz_id":"408","country_code":"385"},
	{"id":"18","name":"Cyprus","pbx_tz_id":"302","country_code":"357"},
	{"id":"19","name":"Czech Republic","pbx_tz_id":"389","country_code":"420"},
	{"id":"20","name":"Faroe Islands","pbx_tz_id":"337","country_code":"298"},
	{"id":"21","name":"France","pbx_tz_id":"387","country_code":"33"},
	{"id":"22","name":"Georgia","pbx_tz_id":"321","country_code":"995"},
	{"id":"23","name":"Germany","pbx_tz_id":"359","country_code":"49"},
	{"id":"24","name":"Gibraltar","pbx_tz_id":"368","country_code":"350"},
	{"id":"25","name":"Greece","pbx_tz_id":"357","country_code":"30"},
	{"id":"26","name":"Hungary","pbx_tz_id":"408","country_code":"36"},
	{"id":"27","name":"Iceland","pbx_tz_id":"339","country_code":"354"},
	{"id":"28","name":"Italy","pbx_tz_id":"391","country_code":"39"},
	{"id":"29","name":"Kazakhstan","pbx_tz_id":"255","country_code":"7"},
	{"id":"30","name":"Kosovo","pbx_tz_id":"358","country_code":"383"},
	{"id":"31","name":"Liechtenstein","pbx_tz_id":"402","country_code":"423"},
	{"id":"32","name":"Lithuania","pbx_tz_id":"405","country_code":"370"},
	{"id":"33","name":"Luxembourg","pbx_tz_id":"379","country_code":"352"},
	{"id":"34","name":"Malta","pbx_tz_id":"381","country_code":"356"},
	{"id":"35","name":"Moldova","pbx_tz_id":"365","country_code":"373"},
	{"id":"36","name":"Monaco","pbx_tz_id":"384","country_code":"377"},
	{"id":"37","name":"Montenegro","pbx_tz_id":"388","country_code":"382"},
	{"id":"38","name":"Netherlands","pbx_tz_id":"355","country_code":"31"},
	{"id":"39","name":"North Macedonia","pbx_tz_id":"396","country_code":"389"},
	{"id":"40","name":"Poland","pbx_tz_id":"407","country_code":"48"},
	{"id":"41","name":"Portugal","pbx_tz_id":"376","country_code":"351"},
	{"id":"42","name":"Republic Ireland","pbx_tz_id":"367","country_code":"353"},
	{"id":"43","name":"Romania","pbx_tz_id":"362","country_code":"40"},
	{"id":"44","name":"Russia","pbx_tz_id":"385","country_code":"7"},
	{"id":"45","name":"San Marino","pbx_tz_id":"393","country_code":"378"},
	{"id":"46","name":"Serbia","pbx_tz_id":"358","country_code":"381"},
	{"id":"47","name":"Slovakia","pbx_tz_id":"360","country_code":"421"},
	{"id":"48","name":"Slovenia","pbx_tz_id":"377","country_code":"386"},
	{"id":"49","name":"Spain","pbx_tz_id":"380","country_code":"34"},
	{"id":"50","name":"Switzerland","pbx_tz_id":"410","country_code":"41"},
	{"id":"51","name":"Turkey","pbx_tz_id":"372","country_code":"90"},
	{"id":"52","name":"Ukraine","pbx_tz_id":"375","country_code":"380"},
	{"id":"53","name":"USA","pbx_tz_id":"193","country_code":"1"}
]