TABLE OF CONTENTS
API Documentation
Setera OneCloud API provides services to end users and for Admin.
You can find End User API documentation from here:
You can find Admin API documentation from here:
To activate Admin API, please contact your Setera contact person.
Authentication
To access an API interface in the system an authentication, needs to be done.
Please check how to enable External API authorization for User API from OneCloud Admin portal: https://setera.freshdesk.com/a/solutions/articles/77000303989?lang=en&portalId=77000015078
API Tickets
The server uses a ticket system for allowing external applications access to internal APIs. The token and secret for a ticket are used to authenticate the external application. The tickets are created by system administrators in the administrator web interface in the system. The tickets can be revoked if needed. See the System Administrator's Guide for more information on how to create tickets.
A ticket can be granted for one or several APIs.
Bearer
User APIs can be reached by authenticating with a token, without a secret. This is done by setting Bearer {token} as the value in Authorization in the header.
These APIs can only be reached from a user's token. For example, a superuser cannot use the Contact search API.
User API access (header-based)
| Security Scheme Type | HTTP |
| HTTP Authorization Scheme | Bearer |
HTTP Operations
Setera OneCloud API uses the following HTTP methods for manipulating data:
- GET - read data from a resource, subscribe to data from a resource
- POST - create a resource
- PUT - update a resource
- DELETE - remove a resource
HTTP clients who are unable to use PUT or DELETE HTTP operations should translate PUT and DELETE to POST operations with an additional X-HTTP-Method-Override header, for example:
- POST /... HTTP/1.1 X-HTTP-Method-Override:PUT
Setera OneCloud responds to POST+X-HTTP-Method-Override request as if the content of the X-HTTP-Method-Override header was the actual HTTP operation requested.
All requests to the server must have the HTTP-headers Content-Type and Accept set to an applicable value according to the respective operation, e.g. application/json or application/xml.
HTTP Response
HTTP Status Codes
Setera OneCloud returns the following HTTP error response codes when encountering problems:
Code | Description |
400 | Bad Request - When receiving an invalid request URI, invalid HTTP header, or invalid message body. Usually including a body consisting of validation result. |
401 | Not Authorized - When missing authorization credentials or not authorized to access the requested resource. |
403 | Not Authorized - The server understood the request but is refusing to fulfill it. The authorization will not help. The current authorization context does not allow the request. |
404 | Not Found - The server does not find the resource that matches the request URI. |
405 | Method Not Allowed - The method specified in the request is not allowed for the resource identified by the request. |
409 | Conflict - The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request. |
500 | Internal Server Error - This is the default code that is used for all unrecognized errors. |
501 | Not Implemented - The request was valid but has not yet been implemented by the Setera OneCloud. |
Setera OneCloud may add a Warning header with warning code 703 to the response in case of errors. The header text will contain a log token in the form "Error occurred, see {token}".