Embedded Files
Access Token Creation
Access Token Creation
An access token is created by calling the API authentication endpoint. Together with the access token it is created also a refresh token.
An access token can be used for multiple API calls until expires. When the access token expires, you need to get a new one, following one of these options:
use the refresh token that was provided together with the access token (recommended)
start the authentication process again.
Please keep in mind that the number of authentication process can be limited around 500 per day and per IP address!
One valid token can be used for all modules.
1. First step is to get an authentication token.
Authentication token can be obtain by using either of the following credentials:
SocrateCloud email and password or
Google ID Token previously created by authenticating a SocrateCloud user to Google using Google OAuth2 authentication.
The Google ID Token must be obtained for SocrateCloud. That means the Google OAuth2 authentication must be made using OAuth Client ID of SocrateCloud. This is found on System tenant, tab Tenant Info, section Login with Google Account, field Client ID.
1.1. Obtain authentication token using your SocrateCloud email and password
make a HTTP GET request to method:
https://api.socratecloud.com/webapi/rest/auth/userAuth/{version}?email=username@domain.com&password=userpass
request result should be a valid authentication token
eg.: {"Token":"0eM7Wvqa71XFC9KuDRu2M1h3M7QyfKHX"} for {version} >= 2
eg.: 0eM7Wvqa71XFC9KuDRu2M1h3M7QyfKHX for {version} < 2 or unspecified
1.2. Obtain authentication token using Google ID Token
make a HTTP POST request to method:
https://api.socratecloud.com/webapi/rest/auth/auth-google/{version}
The request body must be a JSON with the following structure:
{
"googleIdToken": "google id token here"
}
request result should be a valid authentication token for the SocrateCloud user having the email address of the Google authenticated user
eg.: {"Token":"0eM7Wvqa71XFC9KuDRu2M1h3M7QyfKHX"} for {version} >= 2
eg.: 0eM7Wvqa71XFC9KuDRu2M1h3M7QyfKHX for {version} < 2 or unspecified
2. Get access token, using authentication token received at step 1
make a HTTP GET request to method:
The following optional filter parameters can be used on the above request:
IsRoleApps: true/false - should be used to return only roles related to SBS Apps or only SocrateCloud roles
SBSAppId: to return only the roles applicable to a specific SBS Application
request result is a JSON object that contains a valid access token and a refresh token for each Tenant/Role that user belongs, as shown below.
{"data":[
{
"AD_Client_ID":1000001,
"AD_Role_ID":1000002,
"AD_User_ID":1000054,
"ClientName":"TEST1",
"RoleName":"Rol Admin",
"RoleType":"Admin"
"UserName":"User Name",
"accessToken":"b0C3Kf4SdM7ZQEwfW1rw4eRQ81HexwCj",
"refreshToken":"pwZKRdPDqVUcbqhr8xK5zyxeKHqbt4fV",
"IsRoleApps": false,
"SBSAppId": null
},
{
"AD_Client_ID":1000001,
"AD_Role_ID":1000058,
"AD_User_ID":1000 54,
"ClientName":"TEST1",
"RoleName":"Rol User",
"RoleType":"User"
"UserName":"User Name",
"accessToken":"T2l9CeZnM37TZlsE1mxF9Qez3V5XQvse",
"refreshToken":"pwZKRdPDqVUcbqhr8xK5zyxeKHqbt4fV",
"IsRoleApps": true,
"SBSAppId": "938082f0-e53e-11ee-8049-d952222a665e"
}
]
}
In this example, for these username and password, the system returns 2 JSON objects because the user has 2 roles (on one tenant). It is possible that the user could have different roles on different tenants. All these cases are returned as separate objects into JSON.
Choose the access token and refresh token that corresponds to the specific Role and Tenant for which you want to make API calls.
For RoleType, the list of values is:
"Admin" - in case the role of the user has IsAdministrator true;
"Customer" - in case the role of the user has IsUseBPRestrictions true AND the role type is "Role Web Store";
"Seller" - in case the role of the user is of type "Role Comercial Customer"
"Supplier" - in case the role of the user is of type "Role Comercial Vendor"
"User" - none of above.
Starting with SocrateCloud v17.11 the response of available roles is dependent by IP access limitations! Only the roles that can be accessed from your IP will be listed here.
3. When the access token expires and no longer works to make API calls, you can use the refresh token that was provided together with the access token, to obtain a new pair of access token and refresh token. The old refresh token once used, becomes invalid.
https://api.socratecloud.com/webapi/rest/auth/refreshAccessToken/{version}?refreshToken=pwZKRdPDqVUcbqhr8xK5zyxeKHqbt4fV
JSON returned:
{
"accessToken": "CRcwceNzVqFEYyZdu7BgJaBGvgYGPF9S",
"refreshToken": "3GdTveKeHRCnsDW9Tc3ujxBxNzNg7Luu"
}
Note: you can logout (invalidate token) using HTTP POST : https://api.socratecloud.com/webapi/rest/auth/logout/{version}?accessToken=b0C3Kf4SdM7ZQEwfW1rw4eRQ81HexwCj
Note: if any change appear in User Role from SocrateCloud, you must restart the entire auth process, from step 1, to obtain the new roles.
Access Token Usage
Access Token Usage
Access token must be sent as a query string parameter for each API call. The query string parameter name for access token is accessToken.
For example, get the list of allowed organization for selected role:
https://api.socratecloud.com/webapi/rest/auth/roleOrgAccess?accessToken=b0C3Kf4SdM7ZQEwfW1rw4eRQ81HexwCj
Parameters:
IsTrxOrg (Transactional Organizations)
JSON returned:
{"data":[{"AD_Client_ID":1000001,"AD_Org_ID":0,"OrgName":"*","IsReadOnly":"N"},
{"AD_Client_ID":1000001,"AD_Org_ID":1000005,"OrgName":"Organization one","IsReadOnly":"N"},
{"AD_Client_ID":1000001,"AD_Org_ID":1001262,"OrgName":"Organization two","IsReadOnly":"N"}
]
}
Page updated
Report abuse