Here you will find infomation on how to call Cyclos services from 3rd party applications.
The entire service layer in Cyclos 4 is accessible via web services. For a client to use a web service, currently, he needs
to provide the username and password (according to the password configured on the Channels tab for the user configuration).
It is planned for future versions to have access clients, which will belong to an user, being used instead of the username / password authentication.
The available service and API change policy is described here. In terms of security, web services are no more and no less secure than the regular
web access, since the service layer is shared, and the same permissions / authorizations are checked in both cases.
Cyclos offers two types of web services: one for native Java clients and another one which is client-agnostic, using JSON requests / responses
over HTTP. For the latter, a PHP client library is generated from the services, mirroring all services and methods in a PHP-friendly way.
2.1.1. Authentication in web services
There are 3 ways to authenticate an user in web services:
- Using username and password: In this mode, the raw username and password are sent (over HTTPS, so should be secure) on every request.
Uses the "WebServices" channel and doesn't require any additional configuration, besides having the channel enabled.
The drawback is that the username and password need to be stored in the client application, and changing the password on the web (if the same password type is used) will make the application stop working.
- Logging in: In this mode, a first request is made to LoginService.login() operation, returning a session token.
Subsequent requests should pass this session token instead in the subsequent requests.
To finish a session, a request to LoginService.logout() using the session token invalidates the session.
This form also uses the "WebServices" channel and doesn't require any additional configuration.
- Access client: This form requires the configuration of an user identification method of type access client to be setup.
Then, in a member product of users which can use this kind of access, permissions over that type should be granted.
Finally, the user (or an admin) should create a new access client in Cyclos main access, and get the activation code for it.
The activation code is a short (4 digits) code which uniquely identifies an access client for a given user.
To use the access client, on the application side (probably a server-side application or an interactive application), an HTTP POST request should be performed, with the following characteristics:
- URL: <cyclos-root-url>[/network]/activate-access-client
- Standard basic authentication header: Passing the username and password
- Request body: The sole content of the request body must be the activation code