3 OAuth API

Source: This article refers to 3 OAuth API

3.1 Introduction

OAuth 2 is an authorization framework that enables applications to obtain limited access to Coresystems user accounts on an HTTP service. OAuth 2.0 works by ennabling the service that hosts the user account to provide user authentication, and by then authorizing third-party applications to access the user account.

OAuth 2 thus provides secure authorization flows suitable for web, desktop, and mobile applications.


3.1.1 General Protocol Flow

The Client receives the access token from the authorization server and uses it when communicating with resource server.

Tokens are stored in one of the internal Authorization Servers. In case of local scope, the tokes are valid for given cluster only. General scope tokens are valid in any cluster. (Please refer to the Authorization Grant table in section 3.1.2 for more information.)



The following is a description of the transactional flow occuring between the Client, User, Authorization Server, and Resource Server:

  1. The application requests authorization to access service resources from the user.
  2. If the user authorized the request, the application then receives an authorization grant.
  3. The application requests an access token from the Authorization Server by presenting authentication of its own identity along with the authorization grant.
  4. If the application identity is authenticated and the authorization grant is deemed valid, the Authorization Serverthen issues an access token to the application. Authorization is now complete.
  5. The application requests the resource from the Resource Server and presents the access token for authentication.
  6. If the access token is deemed valid, the Resource Server then serves the resource to the application.

The actual flow will differ depending on the type of authorization grant type used.


3.1.2 Authorization Grant

Attention client ID and client secret are generated on request by Coresystems.

The following authorization grants are supported:

Authorization Grant Type Components
Resource Owner Password Credentials client id, client secret, account name, account password
Resource Owner Password Credentials client id, client secret, account name/user name, user password
Client Credentials client id, client secret
Authorization Code authorization_code




Alternative Authorization Grant

  • GET authorization URL for getting the auth code: /api/oauth2/v1/authorize
    • query params:
      • response_type=code, fixed
      • client_id=?
      • redirect_uri=?
    • redirect to confirmation page where user logs in and approves the 3rd party to receive the auth code
    • redirect to redirect_url, will be appended with ?code=
  • POST auth code to token url to retrieve acces token: /api/oauth2/v1/token
    • headers:
      • Authorization: Basic :
      • Content-Type: application/x-www-form-urlencoded
    • body params
      • grant_type: authorization_code
      • code:
      • redirect_uri:

3.1.3 Supported Clusters

Depending on the location of the account, the call will be made to one of the following server clusters:

  • EU
  • DE
  • US
  • CN

Account information, including cluster assignment, are obtained from the Directory API.

This information is passed into requests made to the Data API as follows:

https://{cluster}.coresuite.com


3.2 Access Token

On every access token request, a new access token is generated. Access tokens are valid for 12 hours.


3.2.1 Access Token Scope

The authorization server ignores the scope requested by the client. The scope is calculated based on the client type.

Scope Description Clients
General Allows to use a single access token for requests within any cluster. Admin, Store
Local Allows to use a single access token for requests within single cluster only. Coresystems Cloud clients, Customer Cloud clients

3.2.2 Base URL

The base URL is received from the Directory Service.

https://auth.coresuite.com
Request parameter Description Example
{dataCloudURL} The URL of the Data Cloud server {node}.dc.coresuite.com
{accountName} The account name used during the account registration myAccountName
{userAccountName} The user account name (received by email during the account registration) myUserName
{userAccountPassword} The user account password (please read the observation below) myPassword
{companyName} The company name used during the account registration myCompanyName
{clientIdentifier} The application's identifier that is doing the API call COR_CONNECTOR
{dtoVersions} The version of the resources that we will query for.

Please note how this text is constructed:
Resource1.Version;Resource2.Version;....;ResourceN.Version

Please check the Data Model section.
BusinessPartner.17;ServiceCall.17
{selectStatement} The Sql-Like statement we want to execute. SELECT bp.id, bp.name, sc.id FROM BusinessPartner bp JOIN ServiceCall sc ON bp=sc.businessPartner LIMIT 3

3.3 Refresh Token

Note: Refresh tokens are currently not supported.

3.4 Endpoints

3.4.1 Obtaining Authorization

Request URL

POST /api/oauth2/v1/token

Request Headers

Authorization Basic [client_id:client_secret (base64 encoded)]
Content-Type application/x-www-form-urlencoded

Request Body

grant_type client_credentials or password
username cloud account name or cloud account name/cloud user name (only if grant_type = password)
password cloud account password or cloud user password (only if grant_type = password)

Response

{ "access_token": string, "token_type": string, "expires_in": number, "scope": string, "cluster_url": string, "account": string, "account_id": number, "user": string, "user_email": string, "companies": [ { "id": number, "name": string, "description": string } ] }

3.4.2 Get Access Token

The following example shows how to get the access token for an App/Client, a Cloud Account, and a Company User:


App/Client Authentication


The following example of authentication for an app/client:


POST /api/oauth2/v1/token HTTP/1.1

Host et.dev.coresuite.com
Authorization Basic dGVzdDpzZWNyZXQ=
Content-Type application/x-www-form-urlencoded

grant_type=client_credentials


Cloud Account


The following example is an example of authentication for a Coresystems Cloud account with access to all companies within the account:


POST /api/oauth2/v1/token HTTP/1.1

Host et.dev.coresuite.com
Authorization Basic dGVzdDpzZWNyZXQ=
Content-Type application/x-www-form-urlencoded

grant_type=password&username=cym&password=passwordExample123


Company User


The following example of authentication for a company user, with access to companies controlled by existing subscription and permission settings:


POST /api/oauth2/v1/token HTTP/1.1

Host et.dev.coresuite.com
Authorization Basic dGVzdDpzZWNyZXQ=
Content-Type application/x-www-form-urlencoded

grant_type=password&username=cym/manager&password=passwordExample123


3.4.3 Response

The following is an example of a typical response:

{ "access_token": "77cf4834-a347-4849-839b-4518823a739e", "token_type": "bearer", "expires_in": 43199, "scope": "general", "cluster_url": "https://et.dev.coresuite.com", "account": "testaccount", "account_id" : 284, "user": "manager", "user_email": "test@coresystems.ch", "companies": [ { "id": 957, "name": "SBODemoCH", "description": "OEC Computers (Schweiz)" } ], } 

3.3.4 Error Response

{ "error": "invalid_grant", "error_description": "Bad credentials" }

3.5 Change Password

3.5.1 Request URL

POST /api/oauth2/v1/change_password

Request Headers

Authorization Basic [client_id:client_secret (base64 encoded)]
Content-Type application/x-www-form-urlencoded

Request Body

username Cloud account name or cloud account name/cloud user name (only if grant_type = password)
old_password old password
new_password new password

Response

{ "expires_in": Number }

3.5.2 Obtain Access Token

The following example shows how to get the access token:

POST /api/oauth2/v1/change_password HTTP/1.1

Host et.dev.coresuite.com
Authorization Basic dGVzdDpzZWNyZXQ=
Content-Type application/x-www-form-urlencoded

username=cym/manager&old_password=oldPassword123&new_password=passwordExample123


3.6 Access Protected Resources

3.6.1 Request parameters

Header Query Parameter Required Description
X-Request-ID requestId no Request identifier
X-Client-Version clientVersion yes in case of local scope Client version
X-Client-ID clientId yes in case of local scope Client identifier
n/a account yes in case of local scope and client, account or user authorization Account name
n/a company yes in case of local scope and client, account or user authorization Company name
n/a user yes in case of local scope and user authorization User name
Authorization access_token yes OAuth2 access token, (if used as a header must be prefixed with ‘Bearer ‘)

3.6.2 Example

3.6.2.1 Data API

Using the token to get company Data API. This gets you all the basic CRUD functionality on all data object types in our system, see example for work orders (Service Calls):

GET https://eu.coresuite.com/api/data/v4/ServiceCall?dtos=ServiceCall.20&account=scribe&company=Ambit%20AG&clientIdentifier=COR_CON_NONE

Headers

Authorization Bearer b47217ea-9512-49eb-8c03-ccff67d8e840
Content-Type application/json
X-Client-ID scribe
X-Client-Version 1.0

Response

{ "data": [ { "serviceCall": { "leader": null, "subject": "Need help to install machine", "chargeableEfforts": true, "owners": null, "objectGroup": null, "resolution": null, "syncObjectKPIs": null, "inactive": false, "partOfRecurrenceSeries": false, "contact": "F9A2DB4E9BE047348A2682D63408D176", "problemTypeName": null, "originCode": "-2", "id": "263AADCA529C4D15BC4AA7F9A81AE81E", "problemTypeCode": null, "changelog": null, "endDateTime": "2017-01-25T09:00:00Z", "priority": "MEDIUM", "branches": null, "salesOrder": null, "dueDateTime": "2017-01-31T22:59:00Z", "salesQuotation": null, "udfMetaGroups": null, "orderReference": null, "responsibles": [ "60A745386C71444B96B29FBCCFC46C39" ], "syncStatus": "IN_CLOUD", "statusCode": "-2", "code": "1", "businessPartner": "0113FEDD7C9D4C4085567BDBBF547EF1", "technicians": [], "typeName": "Installation", "chargeableMileages": true, "chargeableMaterials": true, "statusName": "Ready to plan", "orderDateTime": null, "chargeableExpenses": true, "lastChanged": 1483722033305, "createPerson": "387DF047BBF24B66AFC7FD50374F5AE0", "externalId": null, "groups": null, "typeCode": "-4", "createDateTime": "2016-11-03T10:58:57Z", "equipments": [ "48D7C5347B4244B085D8D2F9C9CBE7A8" ], "startDateTime": "2017-01-25T07:30:00Z", "location": null, "udfValues": null, "lastChangedBy": "14523B3D57424338858CB56BBF120696", "incident": null, "remarks": null, "originName": "Telephone" } } []

Note that we didn’t need to pass any specific account username and password for this call. The account and company names are sufficient to identify where to get the data from, while the authorization token, client id and version will give us the permission to get this data. That makes the implementation of your connector/adapter independent of any user, relying instead only on the account.


3.6.2.2 Query API

The following is example for posting more flexibile Query API calls:

POST https://eu.coresuite.com/api/query/v1?account=scribe&company=Ambit%20AG&clientIdentifier=COR_CON_NONE&dtos=BusinessPartner.17

Headers

Authorization Bearer b47217ea-9512-49eb-8c03-ccff67d8e840
Content-Type application/json
X-Client-ID scribe
X-Client-Version 1.0

Body (raw)

{"query":"SELECT bp.name, bp.emailAddress, bp.type from BusinessPartner bp WHERE bp.emailAddress is not null"}

Response

{ "data": [ { "bp": { "emailAddress": "info@coresystems.net", "name": "Coresystems Deutschland GmbH", "type": "CUSTOMER" } }, { "bp": { "emailAddress": "info@coresystems.net", "name": "Coresystems AG", "type": "SUPPLIER" } }, []

3.7 Errors

3.7.1 Obtaining Authorization

The authorization server responds with an HTTP 400 (Bad Request) or 401 (Unauthorized) status code (unless specified otherwise) and includes error and error_description parameters with the response.

error error_description HTTP status code Description
expired_credentials User credentials have expired 400 Password must be changed or has expired. Ask to change credentials.
invalid_client Client authentication failed 401 Wrong client id or client secret. Contact support.
invalid_grant Bad credentials 400 Wrong username or password. Ask for credentials again.
saml_redirect SAML redirect is required! 403 This error tells the client, that the given account and user should be authenticated via the SAML 2.0 Web Browser SSO Profile with the HTTP-Redirect Binding.The initial redirect URL is provide in the additional saml_redirect_url attribute. For example:
 { "error": "saml_redirect", "error_description": "SAML redirect is required!", "saml_redirect_url": "https://corp.dev.coresuite.com/adfs/ls/?SAMLRequest=nVPLbtswELz3KwT...." } 

As the result of the SAML workflow, the client agent will get a response from the cloud's SAML assertion endpoint identical with the response provided by Access Token Request (see above)
unauthorized_client Client is not authorized to use this grant type 401 Client is not allowed to for this Account or User. Contact support.

3.7.2 Expired Credentials

The following is an example error message returned when the credentials have expired:

{ "error": "expired_credentials", "error_description": "User credentials have expired" }

3.8 Password Error Codes

Errors returned by this service follow the structure of Cloud errors (fields: error, message, values).

error message
MC-14 Passwords don’t match
MC-13 Password is not valid
MC-12 Password is to fresh to change
MC-11 Password must contain at least [{0}] upper case letter(s)
MC-10 Password must contain at least [{0}] special character(s)
MC-09 Password must contain at least [{0}] lower case letter(s)
MC-08 Password must contain at least [{0}] letter(s)
MC-07 Password must contain at least [{0}] digit(s)
MC-06 Password must be at least [{0}] character(s) long
MC-05 Password was already used before

3.9 Invalid Token Errors

Errors returned by this service follow the structure of OAuth2 errors (fields: error, error_description).

error error_description HTTP status code Description
invalid_token   401 The token is not valid or expired
invalid_request   400 The request is not valid
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Article is closed for comments.