Appearance
Connecting to the API
A plain-English guide for whoever is connecting a tool to hidma, whether that is you, an IT provider or a developer. It explains the ideas behind the API and what to expect. The exact calls, with examples you can try, are in the API documentation, which opens from Settings › API Access.
You will need
- An application set up in Settings › API Access, with its client ID, client secret and workspace ID. See Setting up API access.
- A tool that can send web requests, such as Postman, Power BI, curl, or your own code.
The words you will see
| Word | What it means |
|---|---|
| Application | The record in hidma that stands for your tool. It holds what the tool is allowed to do. |
| Client ID | The application's username. Starts with app_. |
| Client secret | The application's password. Keep it on a server, never in a web page or a shared file. |
| Workspace ID | Which hidma workspace a request is for. Sent with every request in the X-Hidma-Tenant-Id header. |
| Access token | A pass the tool gets by sending its client ID and secret. It lasts 60 minutes and is sent with every request. |
| Refresh token | A second pass, which lasts 30 days, used to get a new access token without sending the secret again. |
| Scope | One permission, such as clients:read. The access you chose for the application becomes a list of scopes. |
How a connection works
- Get a token. The tool sends its client ID and secret to hidma's token address. hidma checks them and sends back an access token.
- Make requests. For each request, the tool sends the access token and the workspace ID. hidma checks the token is valid and allows that area, then answers.
- Get a new token before the hour is up. The tool either repeats step 1 or uses the refresh token.
The token address and an example request are shown in the window that appears when you create the application, under How to get a token, and at the top of the API documentation.
Access levels and scopes
The levels you chose in Settings › API Access turn into scopes on the token:
| Area | Read only | Read and write |
|---|---|---|
| Clients | clients:read | clients:read and clients:write |
| Projects | projects:read | projects:read and projects:write |
| Jobs | jobs:read | jobs:read and jobs:write |
| Timesheets | timesheets:read | timesheets:read and timesheets:write |
| Users | users:read | Not available. Users are read only. |
If the tool tries something its application is not allowed, hidma refuses with an insufficient_scope error. The fix is to change the application's access in hidma, not the tool.
What the API can do today
| Area | Calls available |
|---|---|
| Clients | List clients, view a client, add a client, update a client |
| Projects | List projects, view a project |
| Jobs | List jobs, view a job |
| Timesheets | List weekly timesheets, view a timesheet |
| Time entries | List time entries, view one, add one, change one, delete one |
| Users | List users, view a user |
Lists come back a page at a time rather than all at once. Time entries can be filtered by person, project, job and date range. Users can be filtered by email address or team.
Each user comes back with their name, email address, job title, team and whether they are active. Users cannot be added or changed through the API; do that in hidma under Users.
Logging time through the API
A time entry is one piece of time: who did it, on which job, on which day, and for how long. It is the single call for logging time. You do not need to create a weekly timesheet first, because hidma finds or creates the right timesheet and row for you.
Each time entry needs:
| Detail | Notes |
|---|---|
| Person | The user the time belongs to. If your other system knows people by email, look up their hidma user by email first (this needs Read only on Users). |
| Job | The job the time was spent on. A project can also be given. |
| Date | The day the work was done |
| Minutes | How long, in minutes. 90 means an hour and a half. |
| Comments | Optional. What was done. |
| Non-billable minutes | Optional. How much of the time should not be billed. Cannot be more than the total minutes. |
hidma protects time that has already moved on:
- Time cannot be added to a timesheet that has been approved. The API refuses with
timesheet_approved. Unapprove the timesheet in hidma first if the time really needs adding. - A time entry that has already been billed or written off cannot be changed. The API refuses with
entry_already_billed.
This is the same protection you get when entering time in hidma itself. See Timesheet Approval.
Limits
| Limit | What it means |
|---|---|
| 60 requests a minute | Per application, across all its workspaces |
| 5 requests at the same time | Per application, across all its workspaces |
| 30 token requests a minute | Per internet address, for getting and cancelling tokens |
If the tool goes over, hidma replies with 429 and says how many seconds to wait in the Retry-After header. Every reply also says how many requests are left this minute, in the X-MinLimit-Remaining header.
Reuse the token
Get a token once and reuse it until it is nearly an hour old. Asking for a new token before every request wastes your limit and slows the tool down.
Keeping the token fresh
An access token stops working after 60 minutes. When that happens, requests fail with 401. The tool can then either:
- Start again by sending the client ID and secret, which is the simplest option, or
- Use the refresh token, which lasts 30 days.
Each time a refresh token is used, hidma sends back a new access token and a new refresh token. The tool must keep the new refresh token and throw away the old one.
A refresh token works once
If a used refresh token is sent again more than 5 minutes later, hidma treats it as stolen and cancels every token made from it. The tool then has to start again with the client ID and secret.
When a user disconnects your tool, it can cancel its own tokens by sending them to hidma's revoke address. The API documentation shows how.
When something goes wrong
Every error comes with a short code and a plain description. The common ones:
| Code | What happened | What to do |
|---|---|---|
invalid_client | The client ID or secret is wrong, or the application is turned off | Check the details. In hidma, check the application is Active. |
invalid_token | The access token has run out or is wrong | Get a new token |
tenant_required | The request did not say which workspace | Send the workspace ID in the X-Hidma-Tenant-Id header |
tenant_not_granted | The application cannot use that workspace | Add the workspace to the application in hidma |
insufficient_scope | The application is not allowed to do this | Change its access in Settings › API Access |
invalid_scope | The tool asked for more than the application is allowed | Ask for less, or change the application's access |
invalid_grant | The refresh token has been used, has run out or was cancelled | Start again with the client ID and secret |
timesheet_approved | The time is for a week whose timesheet is approved | Unapprove the timesheet in hidma, or log the time elsewhere |
entry_already_billed | The time entry has been billed or written off | Leave it, or reverse the bill in hidma first |
429 | Too many requests | Wait the number of seconds in Retry-After, then try again |
Application suddenly turned off?
After 10 wrong secrets in 5 minutes, hidma turns the application off to protect your data. Fix the secret in your tool, then turn the application back on in Settings › API Access.
Trying it out in the API documentation
The API documentation lets you try each call from your browser:
- Open it from the API documentation button in Settings › API Access. You need to be signed in to hidma.
- Click Authorize at the top and enter the client ID and client secret. Leave the scopes unticked to get everything the application is allowed.
- On any call, click Try it out, enter your workspace ID in
X-Hidma-Tenant-Id, and send it.
These are real requests
Trying a call in the documentation works on your real hidma data. Anything you add, change or delete there is added, changed or deleted in your workspace.