OAuth

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

Almost finished!

This authentication method is almost finished, but the following sections will return a 404 error:

Non-Web Application Flow
OAuth Application API

Web Application Flow
Non-Web Application Flow
OAuth Application API

OAuth2 is a protocol that lets external apps request authorization to the private details in a user’s Noko account without requiring their password. Noko supports access to API resources using OAuth because tokens can be easily generated as part of a 3rd party integration and revoked by users at any time.

Before you can start developing with the Noko API, you must first register your application. When you register, you will be given a unique Client ID and Secret. Your Client Secret should not be shared.

There are two supported ways to generate an access token for a specific user from your application: One designed specifically for use by Web Applications, and another that allows other types of applications to list, create, and confirm their Authorization Token for a user.

Since OAuth2 is a complicated authentication protocol, you may want to use an existing library to generate and refresh access tokens.

All OAuth2 authorization requests are made through a single endpoint

https://secure.nokotime.com

Web Application Flow

Below are the steps required to generate an access token for a Noko user through an initial GET request to Noko and a corresponding redirect back to your application.

1. Redirect users to request Noko access

GET https://secure.nokotime.com/oauth/2/authorize

Parameters:

client_id

Required string

The client ID you received from Noko when you registered

Example: client_id=abcdefghi1234

response_type

Required string

Must be set to code. This is usually handled by an OAuth2 client library

state

Optional string

An unguessable random string, which is used to protect against cross-site request forgery attacks.

redirect_uri

Optional string

The URL pointing to your application where users will be redirected to after they have authorized your application to use their Noko data. If no redirect_uri is included in the request, Noko will redirect users to the callback URL configured in the OAuth2 application settings.

Rules:

If a redirect_uri is included in the request, the redirect URL’s host and port must exactly match the configured callback URL and the redirect URL path must reference a subdirectory of the callback URL configured in the OAuth2 application settings.

Examples:

CONFIGURED CALLBACK URL: http://example.com/path

GOOD: https://example.com/path
GOOD: http://example.com/path/subdir/other

BAD:  http://example.com/bar
BAD:  http://example.com/
BAD:  http://example.com:8080/path
BAD:  http://oauth.example.com:8080/path
BAD:  http://example.org

2. Noko redirects back to your site with two parameters:

When the user has authorized your application, Noko will redirect back to your application (either to the URL configured in the OAuth2 application settings, or the url specified in redirect_uri). The redirection will include the following query parameters:

code: string; A temporary code that you will send back to Noko to get the access token. This code confirms that the user authorized your application to use their Noko data, and that you received the request. This temporary code expires shortly after it’s issued, so be sure to use it quickly!
state: string; If you provided a state in your initial request it will be returned back to you. Reject the redirect if this parameter does not match what you previously sent.

Errors:

If the user denied access or there was a problem with the API request, the redirect will include the following query parameters:

error: string; invalid_request: The request was not properly formed.; unauthorized_client: This client is not authorized to request access tokens using this method.; access_denied: The user denied the request to allow this client to access their data.; unsupported_response_type: The server does not support this method of obtaining an authorization code.; server_error: The server encountered an unexpected error and was unable to fulfill the request.; temporarily_unavailable: The server is currently unable to handle the request.
error_description: string; A short explanation of the error

3. POST to Noko to get the access token.

After you have received the temporary code, you will need to POST to Noko to exchange this temporary code for an access token

POST https://secure.nokotime.com/oauth/2/access_token

Parameters:

client_id: Required string; The client ID you received from Noko when you registered your application.
client_secret: Required string; the client secret you received from Noko when you registered your application.
code: Required string; the code you received as a response in step 2.
grant_type: Required string; Must be set to authorization_code. This is usually handled by an OAuth2 client library.
redirect_uri: Required if provided in step 1 string; The URL pointing to your application where users will be redirected to after they have authorized your application to use their Noko data. This must exactly match the value given in step 1.

Reponse

The response will include the following values:

access_token: string; The token you will use to access the API on behalf of a user.
refresh_token: string; The token you will use to refresh the API access token when it expired.
expires_in: integer; The number of seconds until the current access_token expires.
token_type: string; The type of access that has been sent to your application. The default value is bearer.

By default, the response will have the following format:

access_token=abcedfghijk1234567890&expires_in=12345678&refresh_token=poiuytrew098765&scope=&token_type=bearer

However, by modifying your request’s Accept header, you can receive the response in different formats:

Accept: application/json

{
  "access_token": "abcedfghijk1234567890",
  "refresh_token": "poiuytrew098765",
  "expires_in": 12345678,
  "scope": "",
  "token_type": "bearer"
}

Errors

If there was an error getting the access token, the response will be a JSON hash that explains the error:

Status: 400 Bad Request

{
  "error": "invalid_grant",
  "error_description": "The provided access grant is invalid, expired, or revoked (e.g. invalid assertion, expired authorization token, bad end-user password credentials, or mismatching authorization code and redirection URI)."
}

The possible errors are:

invalid_request: The request was not properly formed.
invalid_client: The client provided is invalid.
invalid_grant: The provided authorization grant or refresh token is invalid.
unauthorized_client: The client cannot use this grant type.
unsupported_grant_type: This grant type is not supported by the authorization server.

4. Use the access token to make API requests on behalf of the user

Now that you have an access token for the user, you can use it to make API requests on their behalf. Please review the API basics section on how to include the access token in your requests.

5. Refresh the expired access token

When the access token expires, a 401 error is returned for any associated API requests:

Status: 401 Unauthorized

Once an access token has expired, you will need to use the refresh_token to request a new access_token.

POST https://secure.nokotime.com/oauth/2/access_token

Parameters

client_id: Required string; The client ID you received from Noko when you registered your application.
client_secret: Required string; the client secret you received from Noko when you registered your application.
refresh_token: Required string; The refresh token you were given to refresh the API access token when it expired.
grant_type: Required string; The value must be set to refresh_token. This is usually handled by an OAuth2 client library.

Response

The response will include the following values:

access_token: string; The new token you will use to access the API on behalf of a user.
refresh_token: string; The token you will use to refresh the API access token when it expired.
expires_in: integer; The number of seconds until the new access_token expires.
token_type: string; The type of access that has been sent to your application. The default value is bearer.

By default, the response will have the following format:

access_token=abcedfghijk1234567890&expires_in=12345678&refresh_token=poiuytrew098765&scope=&token_type=bearer

However, by modifying your request’s Accept header, you can receive the response in different formats:

Accept: application/json

{
  "access_token": "abcedfghijk1234567890",
  "refresh_token": "poiuytrew098765",
  "expires_in": 12345678,
  "scope": "",
  "token_type": "bearer"
}

Non-Web Application Flow

Not implemented yet!

This is just a sneak peek into how this feature might work. Attempting to call any actions will return a 404 error.

If your application is not a Web-app, you will need to use the OAuth Authorizations API to generate a new access token for the user. Note that the OAuth Authorization API is only available via Basic Authentication

OAuth Authorizations API

This API allows users to manage their tokens, and is only accessible via Basic Authentication.

Access Tokens are not shared across accounts. When using the OAuth Authorizations API, you will need to specify which account you are accessing. This is done by including the desired account’s subdomain as part of the request URL.

The process for selecting which account to access should be:

Present the user with a list of all the subdomains (with the corresponding avatar) they are associated with.
User selects which account they want to access
Use the user-selected subdomain to access the OAuth Authorizations API

List all the subdomains associated with this user

In order to use the OAuth Authorizations API, you will need to specify which subdomain the user wants to authenticate with. This method returns a list of all the subdomains associated with the user, along with URLs to their respective avatars.

GET https://secure.nokotime.com/subdomains

Response

Status: 200 OK

[
  {
    "name": "testit",
    "avatar": "https://api.nokotime.com/images/avatars/0000/0001/avatar.jpg"
  }
]

List all authorizations

GET https://secure.nokotime.com/authorizations/:subdomain

Response

Status: 200 OK

[
  {
    "id": 1,
    "url": "https://api.nokotime.com/v2/authorizations/1",
    "scopes": [
      "current_user",
      "project"
    ],
    "token": "abc123",
    "app": {
      "url": "http://dabestnokoapp.com",
      "name": "Da Best Noko App",
      "client_id": "98643ycvfjfswx"
    },
    "note": "describes what the token is generated for",
    "note_url": "http://explanation.com/",
    "updated_at": "2011-09-06T20:39:23Z",
    "created_at": "2011-09-06T17:26:27Z"
  }
]

Response if the user is not associated with the subdomain provided

Status: 404 Not Found

Get a single Authorization

GET https://secure.nokotime.com/authorizations/:subdomain/:id

Response

Status: 200 OK

{
  "id": 1,
  "url": "https://api.nokotime.com/v2/authorizations/1",
  "scopes": [
    "current_user",
    "project"
  ],
  "token": "abc123",
  "app": {
    "url": "http://dabestnokoapp.com",
    "name": "Da Best Noko App",
    "client_id": "98643ycvfjfswx"
  },
  "note": "describes what the token is generated for",
  "note_url": "http://explanation.com/",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z"
}

Create a new Authorization Token

When you are not building a Web Application, it might be easier to generate a token using a single POST request.

POST https://secure.nokotime.com/authorizations/:subdomain

Inputs

client_id: Required string; the client key generated for your application.
client_secret: Required string; the client secret generated for your application.
scopes: Optional array of strings; The type of access your application needs to the user’s Noko data.; If no value is provided, then the permissions you chose when you setup your application will be used.
note: Optional string; a note to remind users why the OAuth token was generated
note_url: Optional string; a URL to remind users what app the OAuth token was generated for.

Response

Status: 200 OK

{
  "id": 1,
  "url": "https://api.nokotime.com/v2/authorizations/1",
  "scopes": [
    "current_user",
    "project"
  ],
  "token": "abc123",
  "app": {
    "url": "http://dabestnokoapp.com",
    "name": "Da Best Noko App",
    "client_id": "98643ycvfjfswx"
  },
  "note": "describes what the token is generated for",
  "note_url": "http://explanation.com/",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z"
}

Response if the user is not associated with the subdomain provided

Status: 404 Not Found

Get-or-create an authorization for a specific app

This method checks for an authorization for the specified OAuth application. If the authorization does not exist for this user, it is automatically created.

PUT https://secure.nokotime.com/authorizations/:subdomain/clients/:client_id

Inputs

client_secret: Required string; the client secret generated for your application.
scopes: Optional array of strings; The type of access your application needs to the user’s Noko data.; If no value is provided, then the permissions you chose when you setup your application will be used.
note: Optional string; a note to remind users why the OAuth token was generated
note_url: Optional string; a URL to remind users what app the OAuth token was generated for.

Response if a new authorization is created

Status: 201 Created

{
  "id": 1,
  "url": "https://api.nokotime.com/v2/authorizations/1",
  "scopes": [
    "current_user",
    "project"
  ],
  "token": "abc123",
  "app": {
    "url": "http://dabestnokoapp.com",
    "name": "Da Best Noko App",
    "client_id": "98643ycvfjfswx"
  },
  "note": "describes what the token is generated for",
  "note_url": "http://explanation.com/",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z"
}

Response if an authorization already exists

Status: 200 OK

{
  "id": 1,
  "url": "https://api.nokotime.com/v2/authorizations/1",
  "scopes": [
    "current_user",
    "project"
  ],
  "token": "abc123",
  "app": {
    "url": "http://dabestnokoapp.com",
    "name": "Da Best Noko App",
    "client_id": "98643ycvfjfswx"
  },
  "note": "describes what the token is generated for",
  "note_url": "http://explanation.com/",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z"
}

Response if the user is not associated with the subdomain provided

Status: 404 Not Found

Update an existing Authorization

PUT https://secure.nokotime.com/authroizations/:subdomain/:id

Parameters:

note: Optional string; a note to remind users why the OAuth token was generated
note_url: Optional string; a URL to remind users what app the OAuth token was generated for.
add_scopes: Optional array of strings; The list of scopes to add to this authorization. Adding new scopes allows your application to access additional information from the user’s Noko account. Non-existent scopes, or scopes already applied for this authorization will be ignored.
remove_scopes: Optional array of strings; The list of scopes to remove from this authorization. Removing scopes prevents your application from accessing specific information from the user’s Noko account. Scopes that are not currently applied for this authorization will be ignored.

Response

Status: 200 OK

{
  "id": 1,
  "url": "https://api.nokotime.com/v2/authorizations/1",
  "scopes": [
    "current_user",
    "project"
  ],
  "token": "abc123",
  "app": {
    "url": "http://dabestnokoapp.com",
    "name": "Da Best Noko App",
    "client_id": "98643ycvfjfswx"
  },
  "note": "describes what the token is generated for",
  "note_url": "http://explanation.com/",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z"
}

Response if the user is not associated with the subdomain provided

Status: 404 Not Found

Delete an Authorization

DELETE https://secure.nokotime.com/authorizations/:subdomain/:id

Response

Status: 204 No Content

OAuth Application API

Not implemented yet!

This is just a sneak peek into how this feature might work. Attempting to call any actions will return a 404 error.

These methods are provided to allow your application to confirm a token’s validity and revoke tokens as necessary. They are only accessible by using Basic Authentication as follows:

Username: Your application’s client_id
Password: Your application’s client_secret

Check an Authorization

This method allows you to confirm a token’s validity. The owner must use Basic Authentication when calling this method, where the username is the client_id of the application and the password is its client_secret

GET https://secure.nokotime.com/applications/:client_id/tokens/:access_token

Response if the token does not exist

Status: 404 Not Found

Response:

Status: 200 OK

{
  "id": 1,
  "url": "https://api.nokotime.com/v2/authorizations/1",
  "scopes": [
    "current_user",
    "project"
  ],
  "token": "abc123",
  "app": {
    "url": "http://dabestnokoapp.com",
    "name": "Da Best Noko App",
    "client_id": "98643ycvfjfswx"
  },
  "note": "describes what the token is generated for",
  "note_url": "http://explanation.com/",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z"
}

Revoke all Authorizations for an application

The owner of an OAuth application can revoke every token that has been created for this authorization. The owner must use Basic Authentication when calling this method, where the username is the client_id of the application and the password is its client_secret

DELETE https://secure.nokotime.com/applications/:client_id/tokens

Response

Status: 204 No Content

Revoke a single authorization for an application

The owner of an OAuth application can also revoke a single token that has been created for this authorization. The owner must use Basic Authentication when calling this method, where the username is the client_id of the application and the password is its client_secret

DELETE https://secure.nokotime.com/applications/:client_id/tokens/:access_token

Response

Status: 204 No Content

Topics

Resources

Webhooks

Broadcasts

Account Management

OAuth

Almost finished!

Web Application Flow

1. Redirect users to request Noko access

Parameters:

Rules:

Examples:

2. Noko redirects back to your site with two parameters:

Errors:

3. POST to Noko to get the access token.

Parameters:

Reponse

Errors

4. Use the access token to make API requests on behalf of the user

5. Refresh the expired access token

Parameters

Response

Non-Web Application Flow

Not implemented yet!

OAuth Authorizations API

List all the subdomains associated with this user

Response

List all authorizations

Response

Response if the user is not associated with the subdomain provided

Get a single Authorization

Response

Create a new Authorization Token

Inputs

Response

Response if the user is not associated with the subdomain provided

Get-or-create an authorization for a specific app

Inputs

Response if a new authorization is created

Response if an authorization already exists

Response if the user is not associated with the subdomain provided

Update an existing Authorization

Parameters:

Response

Response if the user is not associated with the subdomain provided

Delete an Authorization

Response

OAuth Application API

Not implemented yet!

Check an Authorization

Response if the token does not exist

Response:

Revoke all Authorizations for an application

Response

Revoke a single authorization for an application

Response

About Noko

Us & our company

Docs

You & your account