10 User API

Source: This article refers to 10 User API

10.1 Overview

The User API enables customers with external systems to create and manage user records and user access rights for Coresystems FSM applications.

10.1.1 Requests by Company and Account

Requests can be made either for the account or for a specific company associated with the account.

Please note the following:

  Note
10.1.1.1 Users are created for an account. Depending on the number of companies in a given account, a user can be created for one or more companies. If a request is made for an account (i.e. without specifying a company in the request) the user record will be created/updated/deleted for ALL companies.
10.1.1.2 A specific company is referenced by the company.
10.1.1.3 User access rights are referenced by the groupId.
10.1.1.4 User records are referenced by the userId.
10.1.1.5 If a user record already exists for one company it won’t be duplicated if the record is create for the account, i.e. all other companies associated with the account.
10.1.1.6 If a userId is updated for one company, it will be updated, if applicable, in all other companies where the record exists.

10.1.2 User API in Swagger

To preview User API functionality, you may use the Coresystems User API Swagger implementation.


10.1.3 User Subscriptions

10.1.3.1 A subscription to use the Coresystems FSM applications is assigned to users whose accounts have been created using the User API.
10.3.1.2 If there is an avaliable, valid subscription that has not beeen assigned to a user, the subscription will be assigned to the user.
10.3.1.3 If there is no avaliable, valid subscription, a new subscription valid for one month will be created and assigned to the user. Each account can only have a maximum of 25 subscriptions created this way.
10.3.1.4 If a user is deleted, a subscription will be unassigned from that user. This subscription can be reused when creating a new user.

10.2 Access

The User API uses Oauth 2.0 for authentication. This token is then used in the Authorization header as the bearer.

Attention: In order to receive an access token, you must have ADMINISTRATOR or SUPERUSER privileges.

10.2.1 Get Access Token

The following example shows how to get the access token for a Cloud Account or a Company User:


Cloud Account


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


POST https://auth.coresuite.com/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 https://auth.coresuite.com/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


10.2.2 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)" } ], } 

10.2.3 Error Response

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

10.2.4 Supported Clusters

Depending on the location of the account, requets 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 User API as follows:

https://{cluster}.coresuite.com

Please note that the example requests contained in this document use the DE cluster. This should be replaced with the cluster associated with your account.


10.3 GET Users

Receive a list of users associated with the account or specific company.

IMPORTANT The groupId returned in a valid GET request is used in the POST request to associate a user with a user role/permission group.

10.3.1 Request

Method URL
GET de.coresuite.com/api/user/v1/users?account={accountName}

10.3.2 Headers

Header Parameter Description Required
X-Request-ID requestId Request identifier Required
X-Client-Version clientVersion The client version Required
Authorization bearer OAuth 2.0 token. Required

10.3.3 URL Parameters

Parameter Type Description Required
account String The name of the account for which the request is being made. Required
Page Integer The amount of results per page you wish to return.  
Size Integer The number of records per page you wish to return .  
Offset Integer The offset to be taken according to the page count and page size  
Sort Array of strings Sorting critera in the format: property (ascidesc). Default sort order is ascending. Multiple sort criteria are supported.  

10.3.4 Response

Status Response
200 OK
400 Bad Request “The [account] parameter is invalid”
401 Unauthorized
403 Forbidden
404 Not found

10.3.5 Example Response

{ "content": [ { "companies": [ { "companyId": 1345, "groupId": 123456 // This value is used in POST, PATCH, and DELETE requests for the companyGroupId. } ], "created": "2018-02-08T10:14:08.006Z", "email": "string", "firstName": "string", "id": 0, "lastChanged": "2018-02-08T10:14:08.006Z", "lastName": "string", "phone": "string", "name": "string" } ], "firstPage": true, "lastPage": true, "number": 0, "numberOfElements": 0, "size": 0, "sort": {}, "totalElements": 0, "totalPages": 0 }

10.4 POST User

Create new user record for an account or specific company.

Attention: When creating a user record, the email must be unique in the system.

10.4.1 Request

Method URL
POST de.coresuite.com/api/user/v1/users/{userID}?account={accountName}&company={companyName}

10.4.1.1 URL Parameters

Parameter Description Type Required
userId The unique user ID referenced in the request. Integer Required
account The name of the account for which the request is being made. String Required
company The name of the company. The user will be created for the specified company. If the company parameter is not present, a user will be created for all companies belonging to the given account. Please refer to the diagram above for specific logic. String Optional

10.4.2 Headers

Header Query Parameter Description Required
X-Request-ID requestId Request identifier Required
X-Client-Version clientVersion The client version Required
Authorization bearer OAuth 2.0 token. Required

10.4.3 Body

A POST request to the User API must contain the following:

Value Description Type Required
companyGroupID The company group ID with which the user is associated. The company group ID contains both the permissions/access rights and user role information. This value is obtained from the GET users request. Integer Required
email The email address of the user. The email must be unique. String Required
firstName The first name of the user. String  
lastName The last name of the user. String  
phone The phone number of the user. String  
name The user name of the user. If not present, will use the name present in the email address. Example: john.smith@abc.com > name = john.smith. String  

The following is an example of the body of a POST request made to the User API:

{2 "companyGroupId": 123456, "email": "john.doe@example.com", "firstName": "John", "lastName": "Doe", "phone": "(555) 555-5555", "name": "john.doe" }

10.4.4 Response

Status Response
200 OK
400 User already exists
400 Bad Request “The [account] parameter is invalid”
400 Bad request - “The [company] parameter is invalid”
401 Unauthorized
403 Forbidden
404 Not found
409 Conflict “Person(s) with username [{0}] could not be created nor updated for the companies {1}”

10.4.5 Example Response

{ "companies": [ { "companyId": 0, "groupId": 0 } ], "created": "2018-06-25T07:07:01.312Z", "email": "string", "firstName": "string", "id": 0, "name": "string", "lastChanged": "2018-06-25T07:07:01.312Z", "lastName": "string", "phone": "string" }

10.5 GET by User ID

Get details of a user record by userId.

10.5.1 Request

Method URL
GET de.coresuite.com/api/user/v1/users/{userID}?account={accountName}

10.5.1.1 URL Parameters

Parameter Description Type Required
userId The unique user ID referenced in the request. Integer Required
account The name of the account for which the request is being made. String Required

10.5.2 Headers

Header Parameter Description Required
X-Request-ID requestId Request identifier Required
X-Client-Version clientVersion The client version Required
Authorization bearer OAuth 2.0 token. Required

10.5.3 Response

Status Response
200 OK
400 Bad Request “The [account] parameter is invalid”
401 Unauthorized
403 Forbidden
404 Not found

10.5.4 Example Response

{ "companies": [ { "companyId": 0, "groupId": 0 } ], "created": "2018-06-25T07:07:57.645Z", "email": "string", "firstName": "string", "id": 0, "name": "string", "lastChanged": "2018-06-25T07:07:57.645Z", "lastName": "string", "phone": "string" }

10.6 PUT User

Update existing user record by userId.

Note: batch user update requests is currently NOT supported.

10.6.1 Request

Method URL
PUT de.coresuite.com/api/user/v1/users?account={accountName}&company={companyName}

10.6.1.1 URL Parameters

Parameter Description Type Required
userId The unique user ID referenced in the request. Integer Required
account The name of the account for which the request is being made. String Required
company The name of the company. The user will be updated for the specified company. If the company parameter is not present, a user will be updated for all companies belonging to the given account. Please refer to the diagram above for specific logic. String Optional

10.6.2 Headers

Header Query Parameter Description Required
X-Request-ID requestId Request identifier Required
X-Client-Version clientVersion The client version Required
Authorization bearer OAuth 2.0 token Required

10.6.3 Body

The user id must match the existing user record being updated in a PUT request.

Value Description Type Required
companyGroupID The company group ID with which the user is associated. The company group ID contains both the permissions/access rights and user role information. This value is obtained from the GET users request. For a PUT request, the group ID can be for a different permission / role group. Integer  
id The ID of the user record being updated. This must match the existing record. Integer Required
email The email address of the user. String  
firstName The first name of the user. String  
lastName The last name of the user. String  
phone The phone number of the user. String  
name The user name of the user. If not present, will use the name present in the email address. Example: john.smith@abc.com > name = john.smith. String  

The following is an example of the body of a PUT request made to the User API:

{ "companyGroupId": 112233, "id": 78919, "email": "john.doe@example.com", "firstName": "Johnathan", "lastName": "Doe", "phone": "(555) 555-5555", "name": "john.doe" }

10.6.4 Response

Status Response
200 OK
400 Email must be unique!
400 User account not found
400 Bad Request “The [account] parameter is invalid”
400 Bad request - “The [company] parameter is invalid”
401 Unauthorized
403 Forbidden
404 Not found
409 Conflict “Person(s) with username [{0}] could not be created nor updated for the companies {1}”

10.6.5 Example Response

{ "companies": [ { "companyId": 0, "groupId": 0 } ], "created": "2018-06-25T07:07:01.312Z", "email": "string", "firstName": "string", "id": 0, "name": "string", "lastChanged": "2018-06-25T07:07:01.312Z", "lastName": "string", "phone": "string" }

10.7 DELETE User

Delete an existing user record by userId.

Note: batch user delete requests are currently NOT supported.

10.7.1 Request

Method URL
DELETE de.coresuite.com/api/user/v1/users?account={accountName}&company={companyName}

10.7.1.1 URL Parameters

Parameter Description Type Required
userId The unique user ID referenced in the request. Integer Required
account The name of the account for which the request is being made. String Required
company The name of the company. The user will be updated for the specified company. If the company parameter is not present, a user will be deleted for all companies belonging to the given account. Please refer to the diagram above for specific logic. String Optional

10.7.2 Headers

Header Query Parameter Description Required
X-Request-ID requestId Request identifier Required
X-Client-Version clientVersion The client version Required
Authorization bearer OAuth 2.0 token. Required

10.7.3 Response

Status Response
200 OK
204 No content
400 User account not found
400 Bad Request “The [account] parameter is invalid”
400 Bad request - “The [company] parameter is invalid”
400 Bad Request “User with a given email [{0}] was deleted.”
401 Unauthorized
403 Forbidden

Appendix

Relevant Data Transfer Objects

PageUser DTO

{ content [...] firstPage boolean lastPage boolean number integer($int32) numberOfElements integer($int32) size integer($int32) sort Sort{...} totalElements integer($int64) totalPages integer($int32) }

UserCompany DTO

{ description: Contains information specific to the Company companyName integer($int64) readOnly: true Company id groupId integer($int64) readOnly: true Permission group id }

UserCreateUpdate DTO v1

{ description: User resource representation companyGroupId integer($int64) Permission group id to set for all account companies email string User e-mail address firstName string First name lastName string Last name phone string Phone / mobile number name string Username }

User DTO

{ description: User resource representation companies created string($date-time) readOnly: true Date when user was created email* string User e-mail address firstName string First name id integer($int64) readOnly: true User id name string Username lastChanged string($date-time) readOnly: true Date when user was last modified lastName string Last name phone string Phone / mobile number. }

User Group Permissions

CRUD Operators

The permissions assigned in the Coresystems Store are for CRUD operators (Create, Read, Update, Delete) available in the application:

Operator Description
Create Enables users to create a new resource in the application. For example, applying Create permissions on Alerts for Own, you would enable users assigned to the permission group to creat their own alerts in the application.
Read Enables users to read resources in the application. For example, applying Read permissions on Approvalsfor Own, you would enable users assigned to the permission group** to read approvals if they have been defined as a decision maker.
Update Enables users to update existing resources in the application. For example, by applying Update permissions on Checklist for Own, you would enable users assigned to the permission group to update their own checklists.
Delete Enables users to delete existing resources in the application. For example, by applying Delete permissons on Quotations for None, you would prevent users assigned to the permission group from deleting quotations–even those they create themselves.
Note: Not all CRUD operators are available for every permissions setting.

Operation Permissions

When applying permission settings, there are three options available:

Option Description
All By selecting, the permissions settings will be available for all users associated with the given permission group. For example, if you applied Read on Attachments and assigned it to All, you would be able to read/view all attachments.
Own By selecting, the permissions settings (example Update on Activity) will be available for all users associated with the given permission group. For example, if you applied Update on Activity and assigned it to Own, you would be able to update your own activities.
None By selecting, the permissions settings (example Delete on Quotations) will be available for no users associated with the given permission group. For example, if you applied Delete on Quotations and assignted it to None, you would be unable to delete quotations.

Business Objects

Use the following table to search for the relevant business object options:


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.