Security
This controller works under the system security rules and constraints.
For more details, refer to the Authentication section
Note
The following guidelines are intended to illustrate the features and features of this Web API controller.
Authentication
JWT Token
In order to invoke the REST API, it is necessary to obtain an authentication token via the appropriate service /Auth/Login
For more details, please see the appropriate section of the documentations.
Bearer Authentication
Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens.
For more details, please see the appropriate section of the documentations.
Identification of the calling application
Some of the REST API functions can only be used if (in addition to proper user authentication) a declaration of the calling application is also performed.
For more details, please see the appropriate section of the documentations.
Actions & Paths
These are the REST actions that can be performed via the Web API infrastructure.
The actions are grouped by "topic".
Click on a "topic" to view the different actions contained in it.
Each action corresponds to a method in the class of the Web API controller, and a set of routing paths that can be used to invoke it.
POST: /api/v1/Auth/Activate
Parameters:
| Name | Type | Required | In | Features |
|---|---|---|---|---|
| token | string | NO | Query |
|
Tags:
Consumes:
- application/json
- application/xml
- text/plain
- application/json-patch+json
- text/json
- application/*+json
- text/xml
- application/*+xml
Produces:
- HTTP 400: LoginResult as application/json
- HTTP 400: LoginResult as text/json
- HTTP 400: LoginResult as application/xml
- HTTP 400: LoginResult as text/plain
- HTTP 400: LoginResult as application/octet-stream
- HTTP 400: LoginResult as text/xml
Response: 400 (Bad Request) LoginResult
Samples
Download Postman collection sample
Try this !
POST: /api/v1/Auth/ChangePassword
Parameters:
| Name | Type | Required | In | Features |
|---|---|---|---|---|
| token | string | NO | Query |
|
Tags:
Consumes:
- application/json
- application/xml
- text/plain
- application/json-patch+json
- text/json
- application/*+json
- text/xml
- application/*+xml
Produces:
- HTTP 400: LoginResult as application/json
- HTTP 400: LoginResult as text/json
- HTTP 400: LoginResult as application/xml
- HTTP 400: LoginResult as text/plain
- HTTP 400: LoginResult as application/octet-stream
- HTTP 400: LoginResult as text/xml
Response: 400 (Bad Request) LoginResult
Samples
Download Postman collection sample
Try this !
POST: /api/v1/Auth/Conflict
Routing template:
/api/{version}/Auth/Conflict
Tags:
Consumes:
- application/json
- application/xml
- text/plain
- application/json-patch+json
- text/json
- application/*+json
- text/xml
- application/*+xml
Response:
Samples
Download HTTP 200 response sample
Download Postman collection sample
Try this !
GET: /api/v1/Auth/GetSwagger
Parameters:
| Name | Type | Required | In | Features |
|---|---|---|---|---|
| honorAcceptLanguageHeader | boolean | NO | Query |
|
| bestPracticeOnly | boolean | NO | Query |
|
Tags:
Produces:
- HTTP 200: object as application/json
- HTTP 200: object as text/json
- HTTP 200: object as application/xml
- HTTP 200: object as text/plain
- HTTP 200: object as application/octet-stream
Response: 200 (Success) object
Samples
Download HTTP 200 response sample
Download Postman collection sample
Try this !
POST: /api/v1/Auth/IspAuth
Routing template:
/api/{version}/Auth/IspAuth
Tags:
Consumes:
- application/json
- application/xml
- text/plain
- application/json-patch+json
- text/json
- application/*+json
- text/xml
- application/*+xml
Response:
Samples
Download HTTP 200 response sample
Download Postman collection sample
Try this !
GET: /api/v1/Auth/Limits
Routing template:
/api/{version}/Auth/Limits
Tags:
Produces:
- HTTP 200: IUserLimit as application/json
- HTTP 200: IUserLimit as text/json
- HTTP 200: IUserLimit as application/xml
- HTTP 200: IUserLimit as text/plain
- HTTP 200: IUserLimit as application/octet-stream
Response: 200 (Success) IUserLimit
Samples
Download HTTP 200 response sample
Download Postman collection sample
Try this !
POST: /api/v1/Auth/Login
Routing template:
/api/{version}/Auth/Login
Tags:
Consumes:
- application/json
- application/xml
- text/plain
- application/json-patch+json
- text/json
- application/*+json
- text/xml
- application/*+xml
Produces:
- HTTP 400: LoginResult as application/json
- HTTP 400: LoginResult as text/json
- HTTP 400: LoginResult as application/xml
- HTTP 400: LoginResult as text/plain
- HTTP 400: LoginResult as application/octet-stream
- HTTP 400: LoginResult as text/xml
Response: 400 (Bad Request) LoginResult
Samples
Download Postman collection sample
Try this !
POST: /api/v1/Auth/Logout
Routing template:
/api/{version}/Auth/Logout
Tags:
Produces:
- HTTP 200: Boolean as application/json
- HTTP 200: Boolean as text/json
- HTTP 200: Boolean as application/xml
- HTTP 200: Boolean as text/plain
- HTTP 200: Boolean as application/octet-stream
Response: 200 (Success) ApiActionResult
Samples
Download HTTP 200 response sample
Download Postman collection sample
Try this !
GET: /api/v1/Auth/Me
Routing template:
/api/{version}/Auth/Me
Tags:
Produces:
- HTTP 200: User as application/json
- HTTP 200: User as text/json
- HTTP 200: User as application/xml
- HTTP 200: User as text/plain
- HTTP 200: User as application/octet-stream
Response: 200 (Success) User
Samples
Download HTTP 200 response sample
Download Postman collection sample
Try this !
GET: /api/v1/Auth/Menu
Routing template:
/api/{version}/Auth/Menu
Tags:
Produces:
- HTTP 200: IMenuNodeList as application/json
- HTTP 200: IMenuNodeList as text/json
- HTTP 200: IMenuNodeList as application/xml
- HTTP 200: IMenuNodeList as text/plain
- HTTP 200: IMenuNodeList as application/octet-stream
Response: 200 (Success) ApiActionResult>
Samples
Download HTTP 200 response sample
Download Postman collection sample
Try this !
GET: /api/v1/Auth/Permits
Routing template:
/api/{version}/Auth/Permits
Tags:
Produces:
- HTTP 200: BooleanIEnumerable as application/json
- HTTP 200: BooleanIEnumerable as text/json
- HTTP 200: BooleanIEnumerable as application/xml
- HTTP 200: BooleanIEnumerable as text/plain
- HTTP 200: BooleanIEnumerable as application/octet-stream
Response: 200 (Success) array of bool
Samples
Download HTTP 200 response sample
Download Postman collection sample
Try this !
POST: /api/v1/Auth/PreActivate
Parameters:
| Name | Type | Required | In | Features |
|---|---|---|---|---|
| token | string | NO | Query |
|
Tags:
Produces:
- HTTP 400: LoginResult as application/json
- HTTP 400: LoginResult as text/json
- HTTP 400: LoginResult as application/xml
- HTTP 400: LoginResult as text/plain
- HTTP 400: LoginResult as application/octet-stream
- HTTP 400: LoginResult as text/xml
Response: 400 (Bad Request) LoginResult
Samples
Download Postman collection sample
Try this !
POST: /api/v1/Auth/PreLogin
Routing template:
/api/{version}/Auth/PreLogin
Tags:
Consumes:
- application/json
- application/xml
- text/plain
- application/json-patch+json
- text/json
- application/*+json
- text/xml
- application/*+xml
Produces:
- HTTP 400: LoginResult as application/json
- HTTP 400: LoginResult as text/json
- HTTP 400: LoginResult as application/xml
- HTTP 400: LoginResult as text/plain
- HTTP 400: LoginResult as application/octet-stream
- HTTP 400: LoginResult as text/xml
Response: 400 (Bad Request) LoginResult
Samples
Download Postman collection sample
Try this !
POST: /api/v1/Auth/Recover
Parameters:
| Name | Type | Required | In | Features |
|---|---|---|---|---|
| username | string | NO | Query |
|
| recoverUserId | integer | NO | Query |
|
| recoverCustomerId | integer | NO | Query |
|
Tags:
Response:
Samples
Download HTTP 200 response sample
Download Postman collection sample
Try this !
POST: /api/v1/Auth/Refresh
Routing template:
/api/{version}/Auth/Refresh
Tags:
Consumes:
- application/json
- application/xml
- text/plain
- application/json-patch+json
- text/json
- application/*+json
- text/xml
- application/*+xml
Produces:
- HTTP 400: LoginResult as application/json
- HTTP 400: LoginResult as text/json
- HTTP 400: LoginResult as application/xml
- HTTP 400: LoginResult as text/plain
- HTTP 400: LoginResult as application/octet-stream
- HTTP 400: LoginResult as text/xml
Response: 400 (Bad Request) LoginResult
Samples
Download Postman collection sample
Try this !
POST: /api/v1/Auth/Session
Routing template:
/api/{version}/Auth/Session
Tags:
Consumes:
- application/json
- application/xml
- text/plain
- application/json-patch+json
- text/json
- application/*+json
- text/xml
- application/*+xml
Response:
Samples
Download HTTP 200 response sample
Download Postman collection sample
Try this !
GET: /api/v1/Auth/Stats
Routing template:
/api/{version}/Auth/Stats
Tags:
Produces:
- HTTP 400: UsageStats as application/json
- HTTP 400: UsageStats as text/json
- HTTP 400: UsageStats as application/xml
- HTTP 400: UsageStats as text/plain
- HTTP 400: UsageStats as application/octet-stream
Response: 400 (Bad Request) UsageStats
Samples
Download Postman collection sample
Try this !
POST: /api/v1/Auth/Token
Parameters:
| Name | Type | Required | In | Features |
|---|---|---|---|---|
| request | TokenRequest | NO | Query |
|
Tags:
Response:
Samples
Download HTTP 200 response sample
Download Postman collection sample
Try this !
POST: /api/v1/Auth/ValidatePassword
Parameters:
| Name | Type | Required | In | Features |
|---|---|---|---|---|
| token | string | NO | Query |
|
Tags:
Consumes:
- application/json
- application/xml
- text/plain
- application/json-patch+json
- text/json
- application/*+json
- text/xml
- application/*+xml
Response:
Samples
Download Postman collection sample
Try this !
Definitions
The following definitions describe the structure of the datamodels involved in the various REST operations that can be performed for this controller.
Some definitions are subjected to polymorphic serialization, and therefore their complete polymorphic scheme is reported.
| Name | Description |
|---|---|
| Brand | Brand |
| Capabilities | Capabilities |
| ConflictSessionRequest | Conflict Session Request |
| CredentialsRequest | Credentials Request |
| IMenuNode | Menu Node |
| IUserLimit | User Limit |
| JToken | J Token |
| LoginResult | Login Result |
| MessageCode | Message Code |
| PasswordChangePayload | Password Change Payload |
| RefreshTokenRequest | Refresh Token Request |
| SecurityPageMenu | Security Page Menu |
| SecurityPolicyRule | Security Policy Rule |
| TokenRequest | Token Request |
| UsageStats | Usage Stats |
| User | User |
Errors
The controller actions will generate errors for the following cases:
- Status 400: Badly formed queries e.g. filter parameters that are not correctly encoded
- Status 401: Authentication failures e.g. unrecognised keys
- Status 403: Forbidden. The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource, or may need an account of some sort.
- Status 404: Not found. Unknown resources e.g. data which is not public
- Status 409: Conflict. Indicates that the request could not be processed because of conflict in the current state of the resource, such as an edit conflict between multiple simultaneous updates.
- Status 500: Server errors e.g. where something has gone
Errors are formatted in JSON
Versioning
It is possible to select the web services version using the {version} token
/api/{version}/{controller}/{details}/{action}/{id}?{querystring}
The token {version} can contain both "exact" values and the special "latest" alias, which identifies the most recent version among those existing in the system.
In general, the use of the special "latest" alias is strongly recommended.
If you want to be particularly "conservative" and adherent to a specific version, specify the name explicitly (eg "v1").
Routing
The system use the following routing syntax, consisting of a sequence of "path-tokens" (the request parameters):
{schema}://{host}/api/{version}/{controller}/{details}/{action}/{id}?{querystring}
The tokens identify respectively:
- {host} -> HOST of the URL
- {version} -> version of web services
- {controller} -> name of the service (controller) you want to invoke
- {details} -> optional detail level of the returned JSON (if applicable)
- {action} -> optional action (method) invoked in the controller
- {id} -> single optional primary key argument (parameter) of the method in the controller, if it so requires
- {querystring} -> additional parameters and possible "modifiers" of the processing and serialization process
OData
The REST APIs are internally based on the Microsoft WebAPI technology, and are largely compliant with the REST specifications, OData v3 and OData v4.
Functions and details related to OData
For more details and specifications regarding the general criteria to adopt when using the OData functions, refer to the basic guide on the topic
Options
The REST API functions implemented in CRM in Cloud include a vast set of options that allow you to adapt the structure and shape of JSON packages according to your needs and preferences.
Unlike the parameters, which are specified in the URL route (through tokens and querystring), the options must instead be passed through the HTTP headers of the request.
As from RFC6648 all the options passed through HTTP headers have in their name the custom prefix "Crm-".
If a certain option is not specified, the system will use the default value specific to the {version} indicated in the URL.
For a complete discussion of options and polymorphic serialization, refer to the general guide on the subject
Swagger
Below you can download the JSON descriptor in Swagger/OpenAPI format