Cezanne HR API

The Cezanne HR API has been created to allow integration with other products and services.

The Cezanne HR API (Application Programming Interface) has been created to allow integration with other products and services, along with enabling clients and third parties to integrate data with their own internal applications or create new ones.

How has the API been developed?

The API has been developed based on the Open Data Protocol (oData), which is built on web technologies such as HTTP and popular methodologies such as REST (Representational State Transfer). The API can return data either in XML (Extensible Markup Language) or JSON (JavaScript Object Notation).

Access to the API can also be restricted to specific users, with access to data matching the main application. For example, if Joe Bloggs can only see people in the UK through the main application, the same restrictions will apply when using an application via the API.

Authentication

The Cezanne API uses the oAuth 2.0 protocol to manage authentication and authorisation.

As HR data can be confidential, the API is secured and you must request an access token before being able to retrieve and / or modify any data.

1. Request a new API application from the Cezanne Support Team.

  • The support team will send you the Client ID and Client Secret for the application.
  • The set of values varies based on what type of application you are building. For example, a JavaScript application does not require a client secret, but a web server application does.

2. Generate an Access Token from the Cezanne Authorisation Server. - In order to access data, you must request an access token. A single access token can be granted different scopes to access the API. A scope controls the set of resources and operations that an access token permits. During the access-token request, your application sends one or more values in the scope parameter. - Using the application details, you can request an access token using a browser redirect. The request requires an authentication step where the user logs in with their Cezanne HR credentials. - After logging in, the user is asked whether they are willing to grant the permissions that your application is requesting. - If the user grants permission, the authorisation server sends your application an access token (or an authorisation code that can be used to obtain an access token). - If the user does not grant the permission, the server returns an error.

3. Use the Token to access Cezanne APIs. - Once you have generated the access token, you should send it to the API in an HTTP authorisation header. - An access token can only be used for the scope of the application. E.g. If an access token is issued read-only permission, you cannot insert / update data against an API. - Access tokens can be used multiple times for operations requiring the same level of permissions.

4. Refresh the token if necessary. - Access tokens have limited lifespans. If your application needs access to an API beyond the expiry of a single access token, it can obtain a refresh token. - A refresh token allows your application to obtain new access tokens. - Refresh tokens should be saved in secure long-term storage as they generally remain valid for long periods of time. -

Generate Token Using Client ID and Secret

If you are building an app which simply queries or writes to the API with no additional user authorisation required, you should use an encoded Client ID and Secret to generate an access token. The Client ID and Secret can be obtained from the Support Team.

The Token can be generated by running a POST request to the Token Endpoint:

Token Endpoint

https://w3.cezanneondemand.com/CezanneOnDemand/OAuth/Token

The request should include a Basic Authorisation header with the encoded Client ID and Secret and it should include the following parameters in the body:

Parameter Value(s) Description
grant_type client_credentials As you are just using Id and Secret, this should be set to client_credentials.
scope should be set to the scope value that the support team has set up for you http://www.cezannehr.com/auth-scope/APIRead http://www.cezannehr.com/auth-scope/APIWrite

The actual request might look like:

POST https://w3.cezanneondemand.com/CezanneOnDemand/OAuth/Token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: w3.cezanneondemand.com
Authorization: Basic [ENCODED_CREDENTIALS]

grant_type=client_credentials&
scope=http://www.cezannehr.com/auth-scope/APIRead

Using Authorisation Process Flow

If you are building an app which requires user's to authorise their scope (e.g. Mobile Application, SSO Application), you should use the Authorisation Process Flow described below:

  1. The authorisation process begins by redirecting a browser (popup, or full page if needed) to the Authorisation Endpoint with a set of query parameters that indicate the type of access the application requires (scopes).
  2. The user logs in and grants permission, this results in an authorisation code.
  3. The caller receives the authorisation code in the query string.
  4. After receiving the authorisation code, the application can exchange the code for an access token and a refresh token.
  5. The application presents its Client ID and Client Secret (obtained during application registration) along with the authorisation code to obtain an access token and refresh token.
  6. Once the application receives an access token, it can then access the API. If a refresh token is present in the authorisation code exchange, then it may be used to obtain new access tokens at any time.

Authorisation Request

The authorisation request is performed by invoking the Cezanne HR authorisation endpoint.

The endpoint is accessible over SSL only.

Authorisation Endpoint

https://w3.cezanneondemand.com/CezanneOnDemand/OAuth/Authorize

This endpoint manages the authorisation process, authenticating the user and handling user consent.

The query string parameters supported by Cezanne are:

Parameter Value(s) Description
response_type code Determines if the Cezanne OAuth 2.0 endpoint returns an authorisation code.
client_id The client_id value sent from the Support team when registering your application. Indicates the client application performing the request. This value is case sensitive.
redirect_uri* One of the redirect_uri values registered for the application by the Support team. The address that the response is sent to by the authorisation server. This value is case sensitive and must match the configured one, including the trailing '/'.
scope A space delimited string representing the permissions requested by the application. The permissions used to access the API. THe user has to grant the application permission to use the requested set of permissions in the user consent page.
auto_approve** A boolean value: It can be 'true' or 'false' (without quotes) This is an optional parameter which is defined by the Support team when registering your application.
state Any string value. A string that is sent to the server representing the state of the application. This string is then returned in the response. Usage of this parameter can be preventing cross-site-request forgery or preserving some application state. This parameter is not mandatory and can be omitted.

*Redirect URI

When you ask the Support team to register an application, you will need to specify your redirect URIs. They are used to return the authorisation code to your application.

The authorisation code is always returned as a query string parameter on the client. To receive the authorisation code on this URL, your application must be listening on the local web server.

For your application you can use:

x-cez://oauth-callback/

When this value is used, your application may intercept the navigating event of the browser control, disable the current navigation and get the authentication code available on the query string.

**Auto Approve

The auto_approve parameter is an optional parameter which is configured when the application is registered by the Support team.

The available options for the “Auto approve mode” are:

  • Disabled - The authorisation page is always displayed to the final user and the auto_approve parameter is ignored.
  • Automatic - The authorisation page is displayed only the first time the user authorises the application and the auto_approve parameter is ignored.
  • OnDemand - The authorisation page is displayed at least the first time the user authorises the application. For subsequent authorisations the auto_approve parameter specifies whether the authorisation page should be displayed. By default the auto_approve parameter is false.

Authorisation Request Example

https://w3.cezanneondemand.com/CezanneOnDemand/OAuth/Authorize?
client_id=oauth2democlient.app.cezannehr.com&scope=http://www.cezannehr.com/auth-scope/APIRead http://www.cezannehr.com/auth-scope/APIWrite&redirect_uri=x-cez://oauthcallback/&response_type=code

Authorisation Response and Token Exchange

After the application receives the authorisation code, it may exchange it for an access token and a refresh token. This request is an HTTP post to the token endpoint.

The endpoint is accessible over SSL only.

Token Endpoint

https://w3.cezanneondemand.com/CezanneOnDemand/OAuth/Token

The request can include the following parameters in the body:

Parameter Value(s) Description
client_id The client_id value sent from the Support team when registering your application. Indicates the client application performing the request. This value is case sensitive.
client_secret The client_secret value sent from the Support team when registering your application. A secret for the client ID. Given the nature of the installed applications flow, the client secret cannot be considered confidential.
redirect_uri One of the redirect_uri values registered for the application by the Support team. The address that the response is sent to by the authorisation server. This value is case sensitive and must match the configured one, including the trailing '/'.
grant_type authorization_code As defined in the OAuth 2.0 specification, this field must contain a value of authorization_code.
code A string value. The authorisation code returned from the initial request.

The actual request might look like:

POST https://w3.cezanneondemand.com/CezanneOnDemand/OAuth/Token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: w3.cezanneondemand.com

client_id=oauth2democlient.app.cezannehr.com&
client_secret=A8KbQe6YmLtrhR3WV4Tbz6eqEyWyeaDyMv4c&
redirect_uri=x-cez%3a%2f%2foauth-callback%2f&
grant_type=authorization_code&
code=Pzw5!IAAAAIS6Mcxbxh6W81jE9BCM9YTxstgQPDUmmGSNrtYbCvXwQEAA

A successful response to this request contains the following fields:

Parameter Value(s) Description
access_token A string. The access token.
token_type bearer The token type. This value is used when invoking an API (see next section).
scope A space delimited string representing the permissions granted by the user. The scope string, as specified in the request.
expires_in An integer value. The number of seconds the access token is valid. This value can be used to understnad in advance that the access token is expiring and refresh the token to get a new one.
refresh_token A string. A token that may be used to obtain a new access token, and are included by default for installed applications. Refresh tokens are valid until the user revokes access.

A successful response is returned as a JSON array, similar to the following:

{
 "access_token":"gAAAAEzcUusQbANDjf1bLK-P5PD6L7RV7PbBtXelFvyq_PdIWSYEtw3MnQO",
 "token_type":"bearer",
 "expires_in":600,
 "refresh_token":"qZR6!IAAAAHvezRU3n1Cd7AxX5nDD7ocM19CO2KJgEUcA9ZPwxmutgQEAA",
}

Notes:

  • Other fields may be included in the response. Your application should allow additional fields to be returned in the response. The set shown above is the minimum set.
  • The actual values of code, access_token and refresh_token parameters have been truncated for readability; real codes are quite longer.

Using a Refresh Token

Requesting a new access token is simple. To request a new access token, make HTTPs POST to the token endpoint.

Token Endpoint

https://w3.cezanneondemand.com/CezanneOnDemand/OAuth/Token

These requests must include the following parameters in the body:

Parameter Value(s) Description
client_id The client_id value sent from the Support team when registering your application. Indicates the client application performing the request. This value is case sensitive.
client_secret The client_secret value sent from the Support team when registering your application. A secret for the client ID. Given the nature of the installed applications flow, the client secret cannot be considered confidential.
refresh_token A string value. The refresh token returned from the authorisation code exchange.
grant_type refresh_token As defined in the OAuth 2.0 specification, this field must contain a value of refresh_token.

Such a request will look similar to the following:

POST https://w3.cezanneondemand.com/CezanneOnDemand/OAuth/Token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: w3.cezanneondemand.com

client_id=oauth2democlient.app.cezannehr.com&
client_secret=A8KbQe6YmLtrhR3WV4Tbz6eqEyWyeaDyMv4c&
grant_type=refresh_token&
refresh_token=qZR6!IAAAANgCRnxuzvvVXyWA98E43oqcceBgsgwpM9a986

As long as the user has not revoked the access granted to your application, the response includes a new access token. A response from such a request is shown below:

{
 "access_token":"gAAAAJYAHiYAsO062l6mQW7kwe4qBmL5ZL4IYi3s8W7",
 "token_type":"bearer",
 "expires_in":600,
 "refresh_token":"qZR6!IAAAANj4-b4q4XBe5gE6Oe9hlaNrmKWH2jDiSNJBfuXj0OD7Gt",
}

Notes:

  • Other fields may be included in the response. Your application should allow additional fields to be returned in the response. The set shown above is the minimum set.
  • You should save refresh tokens in long-term storage and continue to use them as long as they remain valid.

Invoking Cezanne APIs

Once your application has obtained an access token, your application can access a Cezanne API by including it in either an access_token query parameter or an Authorization: Bearer HTTP header.

For example, a call to the OData API using the Authorization header looks like the following:

GET https://w3.cezanneondemand.com/CezanneOnDemand/DataService.svc/People?$format=json
HTTP/1.1
Authorization: Bearer
gAAAAAddm7cVRPlfGVBCtZsQzxMjwsbki_EX8U5SXcM9RnJGvaRE9DSTvPAMlpiwyMSQTcXPqjfpgDOuJZxhqzEEBXPhvlGAGnt4jHWQ8dhJ8
Host: w3.cezanneondemand.com

Using the flow for Single Sign-On (SS0)

The previous authentication examples are typical use cases of OAuth2 that allow you to invoke Cezanne APIs to access data like reports, photos or update data.

We have a further specific API named TokenInfo which can be used to identify users and link them to previously registered accounts without having to manage their identities. The Tokeninfo endpoint provides base information related to the logged in user like first name, last name, e-mail address and the UserGuid which uniquely identifies the account.

An example of using this could be setting up users in your application in advance and assigning privileges in that application. Then you can create a relationship between the user in your application and the Cezanne user account using the UserGuid. This means that a user who has already logged in to Cezanne, the application invoking the TokenInfo endpoint can discover the user identity and grant them the required access to your application.

For example, a call to the TokenInfo API using the Authorization header looks like the following:

GET https://w3.cezanneondemand.com/CezanneOnDemand/OAuth/TokenInfo
HTTP/1.1
Authorization: Bearer gAAAAAddm7cVRPlfGVBCtZsQzxMjwsbki_EX8U5SXcM9RnJGvaRE9DSTvPAMlpiwyMSQTcXPqjfpgDOu-JZxhqzEEBXPhvlGAGnt4jHWQ8dhJ8
Host: w3.cezanneondemand.com

This will provide a json result that includes the following information:

{
    "PersonGuid" : "7ab6ef7a-43cd-472f-852a-bbee3992ad19",
    "TenantGuid" : "00000000-0000-0000-0000-000000000000",
    "RoleGuid" : "00000000-0000-0000-0000-000000000111",
    "UserGuid" : "85feff6b-4d94-47c3-b429-6713ac346196",
    "Username" : "hrprof@cezannesw.com",
    "CountryId" : 1,
    "CountryName" : "United Kingdom",
    "EmailAddress" : "hrprof@cezannesw.com",
    "FirstName" : "HR Professional",
    "FormattedName" : "Cheryl Abrahams",
    "LastName" : "HR Professional",
    "LocaleId" : 2057,
    "LocaleName" : "en-GB",
    "RoleHierarchy" : ["00000000-0000-0000-0000-000000000111"],
    "TimeZone" : "Greenwich Standard Time"
}
Field Description
PersonGuid The unique identifier of the people record in Cezanne linked to the user (if an internal user).
TenantGuid The unique identifier of the tenant (Organisation).
RoleGuid The identifier of the user role in Cezanne.
UserGuid The unique identifier of the user account in Cezanne.
Username The identifier of the user in Cezanne.
CountryId The Country Code of the user.
CountryName The Country Name of the user.
FirstName The first name of the person associated to the user account.
FormattedName The full name of the person associated to the user account.
LastName The last name of the person associated to the user account.
LocaleId The Locale Code of the user.
LocaleName The Locale Name of the user.
RoleHierarchy The identifier of the base user role for the user role.
TimeZone The Time Zone of the user in Cezanne.

Google Calendar Sample

We have developed a sample application using v2 of the API which can extract all employee Absences, based on a configured list of Absence Types and Companies and import them into a Google Calendar. This can then be shared within your organisation providing an overall picture of all absences.

To download the sample code, click here.

To download the sample application, click here.

Power Query

You can use the Power Query Excel add-on to access the Cezanne API and produce reports using multiple queries.

For more information about setting this up, see: Setting Up Power Query.

Response Codes

When using the API, the following list of response codes will be returned:

Code Description
200 OK A request that does not create a resource returns 200 OK if it is completed successfully and the value of the resource is not null. In this case, the response body MUST contain the value of the resource specified in the request URL.
201 Created The request has been fulfilled and resulted in a new resource being created.
202 Accepted The request has been accepted for processing, but the processing has not been completed. The request may or may not eventually be acted upon, as it may be disallowed when processing actually takes place.
204 No Content The server successfully processed the request, but is not returning any content. This is the most likely response to a successful delete request.
401 Unauthorised Authentication has failed or not been provided. Your token may have expired or you may have not yet generated a token.
404 Not Found The requested resource could not be found
405 Method Not Allowed The request cannot be used for this record
500 Internal Server Error A generic error message used when there is no other specific message. The most likely scenarios for this message is that you are trying to retrieve / delete a record that doesn't exist or you are trying to insert data that is not supported in a particular field.

PUBLISHER

Cezanne HR

Imports

0