Authentication

Freckle is now Noko! Learn how to migrate your apps here

The Noko API provides multiple different ways to handle authentication in your application, each one suited for a particular type of application. It’s important to pick the right authentication method for your application, so we’ve created the guide below to help you choose the right one:

The examples below use httpie; which returns a pretty-printed and syntax highlighted response, and works on OS X, Linux, and Windows. You should try it out, we really like it!

Which type of authentication should I choose?

OAuth (Strongly recommended)
My application will be running in a production environment, is not a script, or I am concerned about security.
Personal Access Token
My application is a script or for internal use only.

Which authentication method do I choose?

Sending HTTP Header or noko_token parameter for Personal Access Token
My application uses Personal Access Tokens for authentication
Sending HTTP Header or access_token parameter for OAuth access token
My application uses OAuth access tokens for authentication
Basic Authentication using OAuth access tokens
My tools only allow me to use Basic Authentication but I want to take advantage of OAuth’s security benefits.
Basic Authentication using Personal Access Tokens
My tools only allow me to use Basic Authentication and I am using Personal Access Tokens for authentication.
Basic Authentication to interact with the OAuth Authorizations API
I am writing a non-web application that will be using OAuth, and I need to generate an OAuth access token to allow my application to access the API.

Using Personal Access Tokens

Personal Access Tokens allow users to issue individual tokens for apps and revoke them at will—be sure to handle authentication errors in your application. Treat Personal Access Tokens like passwords!

The token has to be sent for each request your application makes to the Noko API.

There are two ways to send the token—examples are given using the cURL command line tool:

As a query parameter named noko_token:

http GET https://api.nokotime.com/v2/timers noko_token==scbp72wdc528hm8n52fowkma321tn58-jc1l2dkil0pnb75xjni48ad2wwsgr1d

As a HTTP header named X-NokoToken:

http GET https://api.nokotime.com/v2/timers X-NokoToken:scbp72wdc528hm8n52fowkma321tn58-jc1l2dkil0pnb75xjni48ad2wwsgr1d

Using OAuth access tokens

Once your application has received an OAuth access token, you can begin making API requests. Note that access tokens can be revoked at any time, so be sure to handle authentication errors in your application.

The token has to be sent for each request made to the API.

There are two ways to send the token—examples are given using the cURL command line tool:

As an OAuth2 Token header:

http GET https://api.nokotime.com/v2/timers Authorization:"Bearer YOUR_OAUTH_ACCESS_TOKEN"

As a query parameter named access_token:

http GET https://api.nokotime.com/v2/timers access_token==YOUR_OAUTH_ACCESS_TOKEN

Basic Authentication

The API supports Basic Authentication as defined in RFC2617. There are two ways Basic Authentication can be used:

API access via OAuth access tokens

You can authenticate using OAuth access tokens. This approach is useful if your tools only support Basic Authentication but you want to take advantage of the security benefits provided by OAuth Access Tokens.

To do so, provide the access token as the username and provide a blank password or a password of x-oauth-basic. For example:

http GET https://api.nokotime.com/v2/entries -a abcdefghijklmnop1234567890:x-oauth-basic

API access via Personal Access Tokens

You can authenticate using Personal Access Tokens. This approach is useful if your tools only support Basic Authentication and you are using Personal Access Tokens for authentication.

To do so, provide the Personal Access Token as the username and provide a blank password or a password of x-noko-token. For example:

http GET https://api.nokotime.com/v2/entries -a scbp72wdc528hm8n52fowkma321tn58-jc1l2dkil0pnb75xjni48ad2wwsgr1d:x-noko-token

To interact with the OAuth Authorizations API

The OAuth Authorizations API allows users to manage their OAuth access tokens and provides non-web applications a way to generate an OAuth access token for the authenticated user.

To use Basic Authentication to interact with the OAuth Authorizations API, simply send the email and password associated with the user.

For example, if you’re accessing the API via httpie, the following command would authenticate with john@test.com as the email. (httpie will prompt you to enter the password).

http GET https://api.nokotime.com/v2/subdomains -a john@test.com