Stripe.com has an example of good API documentation. This open source project was inspired by Stripe: https://github.com/lord/slate Easy to manage and produces a user-friendly result (builds static HTML files so you can publish to collaborate or anywhere else). Just putting it out there.

Jim Page as discussed in our phone call, the user is associated to the OAuth token when they login in step  2 of the OAuth flow to generate the OAuth code. The OAuth code cannot be generated when the user hits the specific URL unless they login to the Collaborate instance, and hence the OAuth Code and generated OAuth token is associated to their account. 

I am still unclear as to how the API knows which Collaborate user you have generated the OAuth token for.  In section 3 of the 'OAuth protocol explanation' I would expect there to be a Collaborate username or userID parameter so that Collaborate can apply the correct permissions to calls made with the respective token.

At no point in the OAuth handshake is it documented that the Collaborate user is specified so how does Collaborate know which user you want the token to apply to?

Jim Page the API token is generated for each specific user. When you make an API call using a specific API token the server determines who that token was created for, and all API calls respond based on that information. So in your case the GetSiteList will only respond with the list of site that the specific user has got access to. 

Thanks for the reply again.  I think when you say user, you mean 'session', so the OAuth token is specific to the user session from our registered client application.  So for example, our client application may have ClientUserA and ClientUserB logged in and would be making API calls on behalf of both those user sessions under two separate OAuth tokens.

What I still can't quite figure out is that if the Collaborate API honours its internal user permissions then surely at some point the Collaborate user must be specified in the API calls.  So for example ClientUserA may have permissions within Collaborate to view Site1 and Site 2 but ClientUserB only has permissions to view Site1.

If we were to make the GetSiteList API call, how would we get the respective responses if we do not at some point specify the collaborate user as I do not see that as a parameter on any of the calls?