How should a client pass a facebook access token to the server?

Question

On every call to my REST API, I require clients to pass user's facebook access token, which authenticates the user. What's best practice for passing this token?

1. maybe as a parameter behind the HTTP question mark

   GET /api/users/123/profile?access_token=pq8pgHWX95bLZCML
   

2. or somehow in the header of the request, similarly to HTTP basic authentication

3. maybe a third option? (I've excluded passing it in a JSON because I want the token get passed in GET calls as well, so JSON wouldn't fit there I think)

Solution

If you look at the API endpoints provided by all popular OAuth providers (Google, Facebook, Pocket, Git etc), you'd see that they all have HTTPS endpoints.

The ways in which you can pass an access token to the provider are -

i) As Query Parameter -

https://yourwebsite.com/api/endpoint?access_token=YOUR_ACCESS_TOKEN

ii) In the request header -

 GET /api/users/123/profile HTTP/1.1
 Host: yourwebsite.com
 Date: Tue, 14 May 2013 12:00:00 GMT
 Authorization: <YOUR_ACCESS_TOKEN>

These two are approaches that are generally supported by most APIs. You can think of doing the same.

iii) Pocket API does not use GET at all. They use POST for all their requests, even for retrieving data. Check this link to see their documentation. Notice that they use POST for retrieving data and pass JSON parameters.

Comments

[zafeiris.m]

Yes, I am using HTTPS anyway. Options (i) and (ii) seem ok to me too, I wouldn't go for option (iii). In (ii), should I include the word Basic or something else to indicate that I need the token there?

[divyanshm]

Well, the general idea is to include the token type... if you are using a Bearer token type, you can have "Authorization : Bearer <YOUR_ACCESS_TOKEN>" , this will tell your app not to look for client credentials.

[Kristofer Källsbo]

Passing the access token in the query string is not recommended! HTTPS still requests the URL, including query string parameters, in clear text. Only the headers and the body is encrypted!

[ldg]

I didn't think HTTPS solved the security problem for GET; it also means the tokens will most likely end up in your web logs, which may be the least of your problems if the logs are compromised but worth noting.

[Johnny Z]

Downvoting.. Passing tokens in query string is not secure.

[wezten]

@KristoferKallsbo The querystring is encrypted - stackoverflow.com/a/2629241/428724.

[Jon-Eric]

@KristoferKallsbo, I think you've misunderstood how HTTPS works. The request for the URL (including the query string) IS NOT sent in clear text. More info here: stackoverflow.com/q/323200/99377

[mrded]

Be careful with "Authorization: <YOUR_ACCESS_TOKEN>" it may conflict with HTTP Basic access authentication.

[gihanchanuka]

@wezten OAuth2 specification, itself doesn't recommend passing access_token via URLs and query parameters. See (last point|tools.ietf.org/html/draft-ietf-oauth-v2-bearer-16#sect‌​ion-4.3) >> " Don't pass bearer tokens in page URLs: Bearer tokens SHOULD NOT be passed in page URLs (for example as query string parameters)."

[martinedwards]

prepending BEARER to the Authorization value solved my issue for the Timetastic API, thanks @zafeiris.m

[Duncan Jones]

"These two are approaches that are generally supported by most APIs." > It would be nice to have a clear answer for Facebook. Does it support both methods or not?