Authentication

The TypePad JSON API uses OAuth as its sole authentication mechanism. Some additional technologies
are used alongside OAuth to provide capabilities that are not supported by OAuth alone, as described
in the following sections. However, OAuth alone is sufficient to make authenticated requests to
the TypePad JSON API.

Making Anonymous Requests

Many of the API endpoints in the TypePad API will accept unauthenticated requests. These are available
over an unencrypted channel at http://api.typepad.com/. The endpoint /users/<id>
can be used by sending a normal HTTP GET request to, for example, http://api.typepad.com/users/typepad.json.
In this URL, the second "typepad" is the profile alias of The TypePad Team.

Anonymous requests are useful for exploring the API, though if an application needs to do any operation
or access any content that is restricted only to a certain user the application will need to first
obtain an OAuth token for the user and then use that OAuth token to make an authenticated request
as described later in this document.

Obtaining an OAuth Token for a User

Before an application can interact with a user's content on TypePad it must obtain an OAuth token
and associated secret. The OAuth token and its secret serve as a set of credentials which connect
the application with the user's TypePad account, allowing the application to perform operations
on TypePad on behalf of that user.

The application must first discover its three OAuth service endpoints by making an anonymous request,
as described above, to the /api-keys/<id> endpoint, using its API key (which serves as its OAuth consumer key)
as the id. In the response is a property named "owner" which contains an Application object which
contains the properties oauthRequestTokenUrl, oauthAuthorizationUrl and oauthAccessTokenUrl.

Using these URLs the application must perform a standard OAuth transaction as described in
the OAuth 1.0a specification. The OAuth specification has full details,
but in summary:

Make a request to oauthRequestTokenUrl, signed with the application's OAuth consumer key, to obtain a temporary request token and secret.

Issue a redirect to the user's browser to take them to oauthAuthoriationUrl, with the query string parameter oauth_token giving the temporary request token obtained in the previous step.

Once the user has approved your application, recieve a redirect to a callback URL within your application acknowleging that the request was approved.

Make a request to oauthAccessTokenUrl, signed with the application's consumer key and the temporary request token, to obtain an authorized OAuth access token and secret which can be used to make authenticated requests as described in the next section.

Libraries are available for most popular programming languages which implement the OAuth protocol,
and developers are advised to make use of these libraries where possible.

Making Authenticated Requests

Once an application has obtained an OAuth token and secret for a user it may use these as credentials
to make authenticated requests on behalf of that user. Authenticated requests are made via an
encrypted channel to https://api.typepad.com/. Anonymous requests are not allowed to the
SSL endpoints.

The OAuth credentials must be provided via a WWW-Authenticate HTTP request header whose scheme
is OAuth, as described in the OAuth 1.0a specification, section 7.
Using the WWW-Authenticate header is required for all endpoints except those few which specifically
permit using the query string.

Authentication for TypePad-powered Sites

Applications which use TypePad to host content, such as Motion communities, use a slight variation
on the standard OAuth flow in order to afford the additional capabilities that these applications require.

An OAuth access token provisioned using the standard OAuth approval process as described above
has access only to act as the user within the user's own blogs. It does not have access to act as
the user in contexts which belong to an application, such as the group which acts as the
main container object for a Motion community.

In order that an application may retain control over content in its context, the TypePad
API requires a different kind of OAuth token which can only be requested by and issued by
that specific application. In order to request this kind of token, an additional parameter
access must be provided in the URL for the authorization page whose value is
app_full, meaning that the application is requesting a token which gives the
application complete access to act as the current user within its own context.

A token issued in this way is not valid for operations on normal TypePad content
such as the user's blogs, and consequently the OAuth approve page uses different copy in
this scenario asking whether the user wishes to join the site rather than whether the
user wishes to grant account access.

Actions taken on a user's behalf by an application in its own context may still indirectly
cause changes to content outside of its context. For example, if an application posts
a photo into its own group as a particular user this action will appear on the user's
TypePad profile and on the events dashboard of any other user who follows that user.

Anonymous Access to Application Content

In order to allow an application to act as an anonymous user within its own context,
applications which themselves own objects are issued a special anonymous access token
which can be used to make requests where there is no authenticated user but the
application itself is authenticated. This token is used in the same way as a
normal OAuth access token for a specific user, but it is provisioned at application
registration time and supplied to the application via configuration rather than by
a request at runtime.

Identifying a Known User

For sites that use TypePad as an authentication service, when a user returns to the site and
the application already has an OAuth token for that user stored, the application
needs a way to identify the remote user so it can know which OAuth token to use.
The "OAuth Identify" service endpoint can be used for this purpose.

Applications may present this flow to the user as a "sign in" flow, as opposed to the
normal OAuth approval flow which is more like a "registration" flow. The OAuth Identify
process can only be used to identify a relationship you already have with a user, not to create
a new one.

As an extension to OAuth, a successful OAuth approval transaction includes an
additional parameter session_sync_token which is an identifier specific to a particular
TypePad user. This token is used with the Identify mechanism, so an application
must store the session sync token along with the oauth token and secret
in order to make use of this facility.

As described in Obtaining an OAuth Token for a User above,
the application must first determine the oauth-identify
endpoint to use by making an anonymous request to the endpoint /api-keys/<id>. The application must then add to this URL a
callback_url argument specifying the URL that will recieve the response and the query string arguments
necessary to make an OAuth protected resource request and redirect the user's browser to the resulting URL.
TypePad will ask the user to sign in if there is no current login session and then redirect to the provided
callback URL. The redirect URL will also be an OAuth protected resource request, so the application takes on
the role of OAuth service provider to verify the signature and then obtains a session sync token from the
session_sync_token query string argument.

If the session sync token is not known to the application, or it is the empty string indicating that no token
has yet been provisioned for the authenticated user, the application may wish to redirect back to the oauth
approve endpoint in order to obtain an OAuth token for this user.

Session Synchronization

The session synchronization API allows a web-based client app to synchronize its local sessions with
corresponding TypePad sessions. This is important in applications where users interact with TypePad
both directly (by having the user's browser load pages directly from TypePad) and indirectly (by
serving pages that use data retrieved from TypePad via server-to-server communication). Session sync ensures that the same
TypePad user is being used in both cases, even if the user signs out of TypePad and signs in as
another user while the application's local session is still active.

Session syncronization is done via a JavaScript file loaded from TypePad. The user's browser will request the
script with the active TypePad session cookies, allowing TypePad to recognise the user and in turn
tell your application whether a session transition is necessary. The script on TypePad uses a
"JSON-P"-like model to return a result.

The URL of the script to load is given in the sessionSyncScriptUrl property of the Application
object for the current application. Applications must concatenate onto the end of this string a query
string containing arguments using standard query string syntax, as follows:

oauth_consumer_key

The consumer key of the requesting application.

oauth_token

The application access token for the requesting application.

oauth_signature

A signature for this request generated as per the OAuth specification.

oauth_signature_method

The signature method used for this request as per the OAuth specification.

oauth_timestamp

A timestamp for this request as per the OAuth specification.

oauth_nonce

A nonce for this request as per the OAuth specification.

session_sync_token

The session sync token that the application believes represents the currently-active session. If the application has no currently-active session, this argument must be provided with the empty string as its value. A session sync token for a particular user is issued along with that user's OAuth token, as described in Obtaining an OAuth Token for a User.

callback_url

A URL on the client site that will process a session transition. TypePad will construct a signed OAuth protected resource request that represents a GET request on this URL, including the results and the OAuth parameters in an appended query string. Along with the OAuth parameters, a new_token parameter will be provided giving the OAuth access token for the current user.

callback_function

(Optional) The name of a JavaScript function to call with the result of this request.

If no callback_function is specified, TypePad will generate a script that redirects to the altered callback_url.
Clients that wish to handle the redirect some other way can specify callback_function, which will cause TypePad
to generate a script which calls this function with a single argument. If this argument is null, this indicates
that no action is required and the callback function may simply return immediately. If a redirect is required,
a JavaScript string is passed in containing a URL which you can send the browser to in order to complete the session
transition. This is the URL that TypePad would have redirected to if you did not include callback_function.

Whether redirected to directly or via specialized behavior in your callback function, the callback endpoint must verify
the OAuth signature in the request and, if valid, adjust the application's local session to refer to the access token
corresponding to the returned session_sync_token. It is assumed that the client application already has the
corresponding token secret in its local data store; if not, the application should act as if the user is not logged
in or invite the user to re-approve the application via a standard OAuth transaction in order to provision a new OAuth token and
secret.

Note that the session synchronization mechanism fails if the client browser is configured to disable third-party cookies.
At the time of writing this is not the default configuration in any popular browser, but some privacy-concious users
may enable this feature in order to prevent cross-site tracking by analytics services and advertising networks. Session
synchronization may prevent a user whose browser has been configured in this way from interacting effectively with a site
which uses this mechanism.