Designing an API with access tokens, how to handle GET requests?

Question

I am building an API that will utilize access tokens so that I can track usage among various departments and for access control. My plan is to utilize the HTTP verbs appropriately - GET will retrieve information, POST will add, DELETE will delete, etc.

My question is, how should I handle access tokens on the GET calls?

Option one:

Is to provide the access token as part of the query string: /api/users/?token=ACCESSTOKEN. The problem I have with this is that the ACCESSTOKEN appears in server logs. This method will also be different than POST or DELETE requests that have the token passed via the body.

Option two:

Provide a body to the request (as you do in a POST request) and one of the parameters is the token. My issue here is that other developers in my company are telling me this isn't a "true GET request" because I'm passing data. The url they call simply looks like this /api/users/ and they provide token=ACCESSTOKEN within the body.

Option three:

Drop using GET and force everything to be a POST. I don't like this idea because for many of these API calls, I'm not creating new resources. I'm simply returning data that just happens to sit behind an API that requires authorization.

Is there an option that I am missing or should refine? I like option 2, but am sensitive to the concerns of other department developers.

Answer 1

Option 4: Authorization Headers and RFC 6750 (Bearer Tokens)

The solution you are looking for has already been specified as part of the OAuth2 standard, but it stands by itself and will be useful in your scenario.

https://www.rfc-editor.org/rfc/rfc6750

All requests from the client will pass in a bearer token (your access token), and it looks like any other request header to the server. The request itself looks like this:

GET /resource HTTP/1.1
Host: server.example.com
Authorization: Bearer mF_9.B5f-4.1JqM

Since it's a widely implemented public standard, you don't have to worry about defining behaviour - just point client-side developers at the RFC. You might also consider implementing the rest of the OAuth2 standard as both a resource server and an authorization server, but that is a lot more work.

Answer 2

Why don't you use request headers? This separates authentication/authorization data from the actual meaningful data of the request, and it can be used for any type of request (using a request body on a get is typically something you shouldn't do.)

Having authorization in the headers allows you to authenticate the user before parsing the body of the request, which is advantageous when you don't want your system wasting time parsing data from an unauthorized user.