API Authentication¶

Policy¶

If you’re using the API to build a third-party application, aimed at non-developer end-users, you should use OAuth. This provides a very smooth setup experience for users, without exposing their core authentication details.

On the other hand, if you’re using the API to build libraries, scripts, or tools for developers - or even if you’re simply writing scripts for your own use - then you should use API tokens. This is more complex for end-users, but much more flexible, and much more simple to get started with as a developer.

If you use the API against the public timetric site, you need to follow our stated policy on this:

• If your application is closed-source, you must use OAuth.
• If your application is open-source, you should make the choice as appropriate for your intended users.

We’re not uptight about definitions of open/closed-source licenses - for the purposes of the policy, “open source” simply means that people can see your source code. If you’re in doubt, contact us.

OAuth¶

A full description of OAuth is beyond this brief guide, but there’s a wealth of information elsewhere.

• For everything on OAuth; the spec, documentation, etc, please see http://oauth.net
• There’s a good introductory tutorial at http://oauth.net/documentation/getting-started
• Example client code for several languages can be found at http://oauth.net/code

As a developer you need to know the following timetric-specific details:

1. Request a Consumer Token from your settings page. A Token consists of a Key and a Secret (but see the note below about consumer secrets).
2. Your app can now ask for a Request Token from https://timetric.com/oauth/request_token/.
3. Once you have your Request Token, send the user to https://timetric.com/oauth/authorize/?oauth_token={request token key} in their web browser. You can also add an optional oauth_callback parameter.
4. Your app can now switch the Request Token for an Access Token at https://timetric.com/oauth/access_token/. This should be stored and used for all subsequent API requests.
5. The OAuth spec defines three signature methods, of which we support two: PLAINTEXT and HMAC-SHA1. We don’t support use of RSA-SHA1.

API tokens¶

A user can request API tokens on their settings page.

An API token consists of a pair of strings; the key and the secret. These can be used on an API level, in the same way as a username/password pair, in an HTTP Basic transaction.

So if you’d been granted an API token like this:

KEY = 'v9QwHxYtpRACCh3Q'
SECRET = 'ZgPCsr2w9pGzFRDV'

then you could use these on the command line, with curl:

curl -i https://$KEY:$SECRET@timetric.com/series/$SERIES_ID/

Nearly every language has a well supported HTTP library of some sort, and every HTTP library has support for HTTP Basic; the API token can bs used by slotting the KEY in where the username is expected, and the SECRET for the password.

And if you’re absolutely intent on building your HTTP transactions by hand, you can do so very easily. Add an extra header into your request; the header name should be Authorization, and the header value should be the string “Basic “, followed by base64-encode("KEY:SECRET"); that is, for the KEY and SECRET above, the header would look like:

Authorization: Basic djlRd0h4WXRwUkFDQ2gzUTpaZ1BDc3IydzlwR3pGUkRW

Secure HTTP¶

Timetric exposes its API over both HTTP and HTTPS. We recommend that wherever possible you use HTTPS access for your applications, since it prevents eavesdropping of your transactions. However, we allow HTTP access to accommodate clients with limited capabilities.

Since HTTP offers no transport-layer security, you should not use it with authentication methods which might expose your credentials. This means that you may not use Basic Auth, or PLAINTEXT OAuth, over HTTP, these may only be used over HTTPS.