Data Sharing Across Systems

Authentication

Each API request sent from a third-party application to the Command Center website will be authenticated and permissioned as if a real user were using the software. The group permissions of the user associated with the API request will determine which fields and employees each API request is allowed to view and/or edit.

To use the API, each user should have one or more secret API keys that identify that user to the API. The API secret key is a 160-bit number expressed in hexadecimal form. This is an astronomically large number of unique keys, which means that guessing an API key is nearly impossible.

To generate an API key for a given user, users should log in and click their name in the upper right hand corner of any page to get to the user context menu. There will be an "API Keys" option in that menu to go to the page.

If an unknown API key is used repeatedly, the API will disable access for a period of time. Users will still be able to log in to the Command Center website during this time. When the API is disabled, it will send back an HTTP 403 Forbidden response to any requests it receives.

At the HTTP level, the API key is sent over HTTP Basic Authentication. Use the secret key as the username and any random string for the password.

For more information about HTTP Basic Authentication, see this helpful wikipedia article.

Making Requests

• All requests made to our APIs must be sent over HTTPS. The SSL certificate used for the HTTPS connection is signed and all implementations should configure their SSL layer to verify it.
• requests are made to a URL that begins with: https://api.baseline.info/
• API requests can be throttled if Baseline deems them to be too frequent. Implementations should always be ready for a 503 Service Unavailable response.
• Implementations should also always be ready for general Internet packet loss resulting in broken connections with no HTTP response.
• Each employee has an immutable employee ID that is unique within a single company that you can use to reference the employee.
• All requests should be in UTF-8.

HTTP Status Codes

Every request includes an HTTP status code with the result. The status code should be examined before the response.

Successful status codes (2xx)

• 200 OK - The request was successful.
• 201 Created - The resource was successfully created. Confirms a success when creating a new employee, time off request, etc.

Client error status codes (4xx)

• 400 Bad Request - The request was invalid or could not be understood by the server. Resubmitting the request will likely result in the same error.
• 401 Unauthorized - Your API key is missing.
• 403 Forbidden - The application is attempting to perform an action it does not have privileges to access. Verify your API key belongs to an enabled user with the required permissions.
• 404 Not Found - The resource was not found with the given identifier. Either the URL given is not a valid API, or the ID of the object specified in the request is invalid.
• 406 Not Acceptable - The request contains references to non-existent fields.
• 409 Conflict - The request attempts to create a duplicate. For employees, duplicate emails are not allowed. For lists, duplicate values are not allowed.
• 429 Limit Exceeded - The account has reached its employee limit. No additional employees could be added.

Server error status codes (5xx)

• 500 Internal Server Error - The server encountered an error while processing your request and failed.
• 502 Gateway Error - The load balancer or web server had trouble connecting to the Command Center app. Please try the request again.
• 503 Service Unavailable - The service is temporarily unavailable. Please try the request again.

You can future proof your code by using the following ranges:

• 200–299 as success
• 400–499 as client request errors
• 500–599 as server errors

System Users & Passport Users

Compatibility Between Versions

Every attempt will be made to make only forward compatible changes to the API. To assist this effort, API consumers should ignore any XML tags and attributes they do not recognize.

The API will support multiple major version numbers of the API. Currently the only version is "v1". If a major API change becomes necessary, we’ll create a new major version number and communicate the change to our partners. We’ll maintain the existing "v1" API for a reasonable period of time.