OAuth 2.0 for Synergist API

Recommended authentication method

The API documentation for Synergist provides example API requests using simple URLs for demoing/testing the API endpoints. However, we do not recommend any live systems use URLs with embedded username & passwords. At the very least API consumers should be implementing hashing to secure passwords (see Hashing - Sha512)

OAuth 2.0

OAuth 2.0 support allows Synergist API users to make requests without the need to include a username and password as a means of authentication. Following the OAuth 2.0 protocol, users can now securely make requests using an access token for authorisation. While the addition of OAuth 2.0 support has removed the need for users to include a username and password in requests, this is still a supported method of authentication in Synergist. For those that wish to enforce a policy that only allows the use of OAuth 2.0 for authentication, a new setting has been added in "System parameters". It can be found on the "Settings" tab under the "Passwords/Access" panel. Note that it is important to first ensure that all existing requests have been updated to use OAuth 2.0 before enabling this setting, not doing so will cause them to fail.

Registering authorised OAuth 2.0 applications in Synergist is simple with the addition of the "Connected apps" area that can now be found in "Utilities". Users can register and manage applications that will use their Synergist site. In here they can manage redirect URLs and client secrets.

Using OAuth 2.0

First login to the web UI as usual and go to Settings -> Utilities. Here you should see an item called "Connected apps". This is where the details for registering applications for OAuth 2.0 live. There is an entry already there for the Synergist mobile app, this entry is not editable. If you create a new app registration, the client ID is automatically created. You then create a secret (this is only shown for that day, after which the secret is obfuscated). More than one secret can be created which allows for easier secret rotation at a later date.

For each app registration you can create any number of callback URLs. Callback URLs have to begin with https:// except for localhost and 127.0.0.1 which can be http:// When using the OAuth 2.0 endpoints, only callback URLs that are registered here will be accepted.

The OAuth 2.0 endpoints you then need are as follows:

(myserver).synergist.cloud/oauth/authorize - this is the authorise endpoint to send the user to where you supply (URL/query) parameters such as client_id, response_type, redirect_uri, scope and state. In addition, for mobile apps or single page applications, it is required (or at least strongly recommended) to use PKCE which means also supplying parameters code_challenge and code_challenge_method (method is usually s256)

The above endpoint will then redirect the user to our login page after which you will be asked for confirm allow/deny access for the registered application.

After a successful login and allowing access, the user is redirected back to the redirect_uri that you used. To complete the process, the calling application should then make a call (POST) to (myserver).synergist.cloud/oauth/token to exchange the authorization code obtained for an access token and a refresh token.

To do this, the call to (myserver).synergist.cloud/oauth/token should have a JSON object in the body with the following properties:

grant_type, client_id, client_secret, redirect_uri and code. For PKCE you would also supply code_verifier.

grant_type should be authorization_code when exchanging the authorization code for a token (as
described above), or refresh_token when renewing an access token you already hold.

• For grant_type=authorization_code, include client_id, client_secret, redirect_uri, code
  — plus code_verifier if you used PKCE.
• For grant_type=refresh_token, include client_id, client_secret, refresh_token. You do
  not need to send code or redirect_uri for a refresh.

Token lifetimes

The authorization code must be exchanged within 10 minutes or it expires and the flow needs to be
restarted from /oauth/authorize. Once your access token expires, use the refresh token to get a
new access/refresh token pair — the user does not need to log in again unless the refresh token
itself has expired or been revoked.

Example response

A successful call to /oauth/token returns:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "openid email profile",
  "expires_in": 1800,
  "token_type": "Bearer"
}

expires_in is the number of seconds until the access token expires (1800 = 30 minutes). Store
both values — you'll need the refresh token later to obtain a new access token without asking the
user to log in again.

Using the access token

Once you have an access token, include it as a Bearer credential in the Authorization header of
your API requests:

GET (myserver).synergist.cloud/jsonapi/activities.json?company=1&modelstructure=activitylist
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

This replaces the user/password (or sha512password) query parameters used elsewhere in this
documentation — with a valid access token, no other credentials are needed on the request.

If a request returns a 401, your access token has likely expired — use your refresh token to
obtain a new one rather than sending the user through the login/consent screen again.

Access tokens

Access tokens are a JWT which can be verified if wanted, but not strictly necessary. The OpenID config and JWKS for that is available in (myserver).synergist.cloud/.well-known/openid-configuration and (myserver).synergist.cloud/.well-known/jwks.json respectively.

There is also a revoke endpoint - (myserver).synergist.cloud/oauth/revoke - this is to provide a way to permanently disconnect from a specific Synergist server. The parameters for the revoke endpoint are: client_id, client_secret and token and these should be provided in the POST body as variables (eg: client_id=xyz&client_secret=abc&token=abc123) The token parameter should contain the refresh token in order to revoke both the refresh token and the access token.