Website logo

Example OAuth workflow

First up, head to the Developer Options page and create an application, you'll be provided with a consumer key and a consumer secret. We’ll be using these as an example for our Sandbox environment:

Acquiring temporary tokens

Before you can begin authorising, you must acquire some temporary request tokens, this is done with a request with an Authorization header. It is built with the following:

Using our example consumer credentials it will look like this: (Note: the oauth_callback value is case sensitive, it must match one of your callback domains or the default callback registered with your application)

Your oauth_callback was set when registering your application, you must use this callback or omit it completely. If you omit it, then the default callback will be used. If you didnt register a callback upon registration and opted to use the out-of-band stream (which provides the user with a PIN number at the end), then specify this as "oob". For information on how this changes the process, see Differences with the out-of-band flow.

The oauth_signature is your consumer secret followed by & at the end.

oauth_signature=160FCF77971DC92A38596288DB071A8CA5%26

You will need to properly encode the & by using UTF-8 encoding: %26. URL encoding is defined specifically in the OAuth 1.0 spec. These characters must not be encoded: alphanumeric characters, "-", ".", "_", "~". All other characters must be encoded (including space, which must be encoded as %20). Additionally the two hexadecimal characters used to represent encoded characters must be uppercase.

To make the Authorization header, you simply append all the values starting with "OAuth". Each value must be URL encoded.

Authorization: OAuth oauth_callback=https%3A%2F%2Fwww.website-tm-access.co.nz%2Ftrademe-callback, oauth_consumer_key=4E0D082355116884742E5F33B8A199F411, oauth_signature_method=PLAINTEXT, oauth_signature=160FCF77971DC92A38596288DB071A8CA5%26

We can now make a request to the server. By making a POST request to https://api.tmsandbox.co.nz/Oauth/RequestToken?scope=MyTradeMeRead,MyTradeMeWrite with the Authorization header, we will get back an oauth_token and oauth_token_secret.

oauth_token=86EE20AFF655C34CB34873449A5F98020B&oauth_token_secret=905448B594595D5A030DC68BE40AE03C2B&oauth_callback_confirmed=true

Remember the oauth_token and oauth_token_secret in your application.

Authorising access to the users account

Point the user to https://www.tmsandbox.co.nz/Oauth/Authorize?oauth_token=[oauth_token] using the token you just got back. In this example, this goes to:

https://www.tmsandbox.co.nz/Oauth/Authorize?oauth_token=86EE20AFF655C34CB34873449A5F98020B

Trade Me handles this step for you. The user is asked to sign in (if they haven’t already) and then asked whether to allow or deny your application access. When the user clicks the Allow button, they will be redirected off to the callback address you provided in the first step, with the oauth_token and oauth_verifier as query string parameters.

https://www.website-tm-access.co.nz/trademe-callback?oauth_token=86EE20AFF655C34CB34873449A5F98020B&oauth_verifier=A1EF8419E7EF8E61EE7FF28D97027EC9F2

The OAuth token is the same as what was provided earlier, but you’ll want to remember the oauth_verifier as you’ll need it for the next request, the call to get the final access token and access token secret.

Acquiring final token and secret

This time we generate the Authorization header with the following parameters, notice that we have the oauth_token from the first step AND the oauth_verifier from the second step. Now we are authenticating on a user level, the user who has just allowed you application access to their account so this means that our signature now uses the token secret:

<consumer-secret>&<token-secret>
160FCF77971DC92A38596288DB071A8CA5%26<span>905448B594595D5A030DC68BE40AE03C2B</span>

Also we now send through the oauth token in the oauth_token header

Now a request can be made to https://api.tmsandbox.co.nz/Oauth/AccessToken with the following header:

Authorization: OAuth oauth_verifier=<span>A1EF8419E7EF8E61EE7FF28D97027EC9F2</span>, oauth_consumer_key=4E0D082355116884742E5F33B8A199F411, oauth_token=<span>86EE20AFF655C34CB34873449A5F98020B</span>, oauth_signature_method=PLAINTEXT, oauth_signature=160FCF77971DC92A38596288DB071A8CA5%26<span>905448B594595D5A030DC68BE40AE03C2B</span>

You will get back a new oauth_token and oauth_token_secret.

oauth_token=FC68E51450D905FE5083921C6057F42262&oauth_token_secret=5333F645901F003CD98A69589C45BBC158

Remember these tokens, as these are yours to use for all future requests to Trade Me with that user until they expire or the user revokes them.

Making your first request

You can get the members watchlist with a simple call to https://api.tmsandbox.co.nz/v1/MyTradeMe/Watchlist/All.xml. To make the call you must once again create an Authorization header to include with the request.

We need:

This time, the oauth_token from the final step of the OAuth process was used.

And this will be the Authorization header for this request:

Authorization: OAuth oauth_consumer_key=4E0D082355116884742E5F33B8A199F411, oauth_token=<span>FC68E51450D905FE5083921C6057F42262</span>, oauth_signature_method=PLAINTEXT, oauth_signature=160FCF77971DC92A38596288DB071A8CA5%265333F645901F003CD98A69589C45BBC158

Now you can make the request to the Watchlist endpoint with the Authorization header, and get back the users watchlist.

<Watchlist xmlns="http://api.trademe.co.nz/v1" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
   <TotalCount>3</TotalCount>
   <Page>1</Page>
   <PageSize>3</PageSize>
   <List>
      <WatchlistItem>
         <ListingId>2348395636</ListingId>
         <Title>Gazebo Heavy Duty 4.5m x 3M With Carry Bag HOT DEALS $1 RESERVE</Title>
         <Category>0004-0375-0582-8360-</Category>
         <StartPrice>1.0000</StartPrice>
         <StartDate>2019-10-08T07:19:45.967Z</StartDate>
         <EndDate>2019-10-15T07:17:00Z</EndDate>
         <ListingLength i:nil="true"/>
         <MaxBidAmount>117.0000</MaxBidAmount>
         <AsAt>2019-10-15T00:26:33.9904399Z</AsAt>
         <CategoryPath>/Home-living/Outdoor-garden-conservatory/Outdoor-furniture/Marquees-gazebos</CategoryPath>
         <PictureHref>https://trademe.tmcdn.co.nz/photoserver/thumb/721448401.jpg</PictureHref>
         <PhotoId>721448401</PhotoId>
         <IsNew>true</IsNew>
         <RegionId>2</RegionId>
         <Region>Auckland</Region>
         <Suburb>Auckland City</Suburb>
         <BidCount>58</BidCount>
         <IsReserveMet>true</IsReserveMet>
         <Note/>
         <NoteDate>1970-01-01T00:00:00Z</NoteDate>
         <CategoryName>Marquees & gazebos</CategoryName>
         <ReserveState>Met</ReserveState>
         <Attributes/>
         <MinimumNextBidAmount>118.0000</MinimumNextBidAmount>
         <IsOnWatchList>true</IsOnWatchList>
         <PriceDisplay>$117.00</PriceDisplay>
         <AdditionalData>
            <BulletPoints/>
            <Tags/>
         </AdditionalData>
         <IsDealer>false</IsDealer>
         <IsLeading>false</IsLeading>
         <IsOutbid>false</IsOutbid>
         <IsInCart>false</IsInCart>
         <MemberBidShippingOption>0</MemberBidShippingOption>
      </WatchlistItem>
   </List>
</Watchlist>

If you’ve made it this far then congratulations, you’ve successfully authenticated and signed requests with OAuth!

Differences with the out-of-band flow

When you specify the oauth_callback as "oob" your application must explicitly ask for the oauth_verifier.

At the Authorization step, instead of sending the user to the callback address, the user is sent to a page containing a PIN code. The PIN code is a seven digit number, and is used as the oauth_verifier at the Access Token stage.