Authentication

Authentication

Introduction

You can access global public data and private data of a User with the Tagcrumbs API. You can read all public data without any form of authentication, that’s why the examples on the Architecture page were displayed in your browser when you clicked on the links.

However, when reading data without authenticating your application, your API calls can be subject to rate limitations in the future. The next paragraphs show how you will be able to authenticate your application and the User.

OAuth

oauth.jpg

Authentication in the Tagcrumbs API is built on the open OAuth protocol, which was designed so that users can authorize other applications to access their data without giving their password away. Many other sites like Twitter, Google or Netflix rely on the OAuth protocol, it is an emerging standard for API authentication and authorization.

On Tagcrumbs we are using OAuth because:

• Tagcrumbs users don’t have to reveal their login credentials to anybody besides Tagcrumbs.

• It can be used by third-party websites and desktop + mobile clients

• Users can revoke access for an application in their settings on our website.

• It is secure, the username and password are not passed in clear text over the Web and a SSL encryption is only needed for a few requests to exchange the tokens, making it much faster.

• We can authenticate applications and check that they are behaving properly, so that we can ensure the best service for everybody.

• It is becoming the standard for accessing APIs and there are many tools and libraries for different programming languages available, making it easy to use.

API Requests

There are the following types of API Requests:

• Unauthenticated Requests
A Request without any authentication, might be blocked in the future or rate limited. Only GET Requests are allowed.

• Signed Requests
The Request is signed by your application (2-legged OAuth), but no user is involved. Used to access all public data without rate limits. Only GET Requests.

• Protected Request
The Request is signed by your application and a User authorized your application to access and change Tagcrumbs data on his behalf. Your application can read all public data and read and modify all the data of the User. All HTTP methods are allowed.

Making Requests

First of all you need a valid Tagcrumbs account. Afterward you can create a new application on http://www.tagcrumbs.com/applications/new.

Copy your Consumer Key and Consumer Secret and keep them in a save place. You will have to use them for all future requests.

Signed Requests

The Request is only signed by your application (2-legged OAuth), no User is involved in this. Use Signed Requests only if you program an application that displays global data and Users are not even able to authorize access for your application. Maybe you want to program an application that just shows a list of Placemarks near a certain location and the User cannot favorite the Placemark or create a new one, Signed Requests will be the way to go. If a User has authorized access for your application just use Protected Requests, for public and for private data.

If you want to allow users to create a new Tagcrumbs User account inside your application (maybe a mobile client?) you can drop us an email with your plans at team@tagcrumbs.com and we might grant your application the rights to do this. The Request to create a new User account would also be a Signed Requests, as there is no User account yet to authorize your application.

If you are using a library to create OAuth Requests you usually use a method of the Consumer to sign the Request without an Access Token.

More information about Signed Requests can be found on http://oauth.googlecode.com/svn/spec/ext/consumer_request/1.0/drafts/1/spec.html.

Protected Requests

Protected (3-legged OAuth) Requests are the main intend behind OAuth. There are three parties involved: Tagcrumbs, your application and a User with a Tagcrumbs account. The User should not enter his username and password into your application, the User only gives the password to the Tagcrumbs website and Tagcrumbs grants your application access to the User’s data. Your application then receives an Access Token which it can use for all further requests.

Let’s assume you want to provide an interface in your application to authorize access. The exchange of the OAuth tokens (“OAuth Dance”) works like this:

1. The User sees a screen or page in your application that has a title of something like “Connect with your Tagcrumbs account” with a big button that says “Connect”

2. The User clicks on the “Connect” button. Your application will now give the Tagcrumbs servers a heads up, that there will be a new Tagcrumbs User coming soon that wants wants to authorize your application. Your application is doing this by sending a Signed Request to https://www.tagcrumbs.com/oauth/request_token (POST).

3. If the Signed Request of your application was valid we will send you a new Request Token as a response to your Request.

4. The User now has to authorize your application on the Tagcrumbs website. Your application will now send the User to a special URL on Tagcrumbs (http://www.tagcrumbs.com/oauth/authorize + Request Token and Callback URL in query string). If you are programming another website you can redirect the User’s browser, if you are programming a desktop or mobile application you can open the site in a new browser window.

5. The User is on the Tagcrumbs website with his browser. If he is not already logged in, he has to login with his username and password, OpenID or Facebook Connect.

6. The User now sees a special page on the Tagcrumbs website, that asks him, if he really wants to give access to your application. If the User clicks on “Yes” we will authorize the Request Token that your application sent us and redirect the User back to the Callback URL that your application appended to the query string. If the Callback URL starts with “http:” the User will be redirected to your web site. If you are developing a mobile or desktop application you could register your own protocol like “your_application:” with the OS and your application will be activated on the User’s device.

7. Your application now knows that the Request Token was authorized, as the User was redirected back to the special Callback URL. Your application can now exchange your Request Token against an Access Token by sending a Request to https://www.tagcrumbs.com/oauth/access_token (POST) with the Request Token that you want to exchange.

8. If the Request Token was authorized by the User and the signature is valid we will send your application an Access Token in the response.

Your application can now use the Access Token for ALL future requests. The Access Token does not expire, it could only be that the User revoked access for your application in the settings section on the Tagcrumbs website.

The Access Token gives you read and write access to all the User’s data. To prove that you have the Access Token your application has to sign all requests with the Consumer Token and the Access Token.

If you want to learn more about OAuth and the details of the “OAuth Dance” check out the websites at the bottom of the page, they provide you with all the nitty-gritty details. It is not wrong to understand the details, but you might not need them, as there are many libraries that hide all the details from you as you can see in the next section.

OAuth Libraries

Most probably your programming language already has some libraries that plug into your HTTP request generator and handle the OAuth-signing of requests transparently, so that you don’t have to worry about it.

Usually the libraries are modeled to provide the easy generation of Protected Requests, if you want to only make Signed Requests it might take a while to find the right methods, but usually they are there, because Signed Requests are also needed for the “OAuth Dance” that is needed to make Protected Requests.

Some of the most important libraries are collected on http://oauth.net/code, but there are even more out there. In the rare case that there is no library out there you can write your own, take a detailed look at the OAuth Spec for this.

Maybe there even is a specialized Tagcrumbs Libraries for your programming language. If this is the case you hardly have to worry about authentication at all, as the library should take care of it.

Further Reading