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.
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.
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:
- The consumer key of the requesting application.
- The application access token for the requesting application.
- A signature for this request generated as per the OAuth specification.
- The signature method used for this request as per the OAuth specification.
- A timestamp for this request as per the OAuth specification.
- A nonce for this request as per the OAuth specification.
- 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.
- 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.
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.