We recommend that all tokens be kept secret and guarded in the same manner as your password. If a token has been compromised by an unauthorized party you can use the Reset button to reset the compromised token.
The API utilizes the following tokens for authentication:
- Consumer Secret Token: This Company account specific token is required for API authentication. This token should only be used for customer solutions for internal company use. AAvailable from Setup > Company > API tab. This token also grants access to the Authenticate URI. By using the Authenticate URI, a company can create an app UI design that utilizes the Login information for a user rather than requiring a User Data Access Token.
- Data Access Token: A special Company account specific data access token that has full access to All Data in the application. Available from Setup > Company > API tab.
- User Data Access Token: This Company account user access token grants an employee access to only the data permitted by his or her security settings as defined in the Dovico software. Available in each user's My Options view (mouse over the employee's name in the upper right corner and select Settings.)
If you are building an Application (App) using the API that will be used by multiple DOVICO Software Company accounts (e.g. an App that can be distributed to the public), then you need to obtain a Developer's Consumer Secret Token:
- Developer’s Consumer Secret Token: This token is required for API authentication but is not company account (database) specific. Contact DOVICO to obtain a Developers Consumer Secret Token.
- Trusted Developer’s Consumer Secret Token: This is a special class of Developer's Consumer Secret Token that is not company account (database) specific and is issued to Dovico vetted 3rd Party Developers and Partners. This token grants access to the Authenticate URI. The Authenticate URI can be used to request a User Data Access token using Dovico Services user credentials. By using the Authenticate URI a developer can create an app UI design that uses Dovico Services login credentials rather than requiring a Data Access Token for authentication. Contact DOVICO to obtain a Trusted Developers Consumer Secret Token.
The API is enabled in the Company view's API tab (Navigation bar > Setup > Company). The Company view is only available to those users with the appropriate security. If you don't have access to the Company view, then ask your DOVICO Administrator for access.
The Consumer Secret token is required for API authentication. This
is used to identify your company when using the API. The Reset button
will generate a new consumer secret key. The previous consumer key
will no longer be authorized to access the API.
The Data access token in this view is a special data access token that
has full access to all data in the application. We suggest that this
token be used in special circumstances where full data access is required.
An example of such a use may be an internal application that integrates
DOVICO Services with a billing system that requires full access to
all time entry and billing data in DOVICO Services. We do not recommend
providing this token to third party applications. The Reset button
will generate a new Data access token. The previous data access token
will no longer be authorized to access the API.
The Allow Employees to use 3rd Party Apps checkbox is used to enable
employees to generate a User Data access token. When this box is checked,
a new field is made available in each users' Options tab in their
Time and Expense entry view. DOVICO's iPhone app for time and expense
entry (DOVICO Mobile) is exempt from this requirement.
The user Data access token is a restricted access token. This token is unique for each user of DOVICO Services and is granted access to data for which that user has access. For example; if a user has only been given access to view his time and expense data using limited access in the application, then the user will only be able to access that information using this token. No other data will be accessible. The Reset button will generate a new user Data access token. The previous user Data access token will no longer be authorized to access the API.
Authentication
Once you have enabled the API and generated access tokens it is possible to connect to the API and access DOVICO Services data. The Consumer Secret token and Data access token are sent to the API using a HTTP header field of an API request. The HTTP header field is required in each request to authenticate and access to data. The header field name is 'Authorization:' followed by the WRAP access_token value and user_token value. Below is an example using the win32 cURL executable.
curl -H "Authorization: WRAP access_token=""client=c97727ec3838427bbec992a043db2408.555&user_token=8f540ff34f0c48baa80868fbc72bcc58.555""" -k https://api.dovico.com/employees/?version=7
Every call to the API must include an Authorization header containing the Consumer Secret/3rd party developer key and the Data Access Token of the user using the API.
The Consumer Secret/3rd party developer key and the Data Access Token value should be URL Encoded before being added to the Authorization header.
The Authorization header is expected in the following format:
Authorization: WRAP access_token="client=TheConsumerSecret&user_token=TheUserToken"
All data is to be passed to the API formatted in US English when it comes to numbers. The API only returns numbers using US English format.
Dates are expected in the following format: yyyy-MM-dd
Paging is set to a default of 1000 records per page.
The maximum amount of data that can be included in a request is currently set at: 5,120 KB (5 MB). If this value is exceeded, a 400 Bad Request error will be returned.