API Design – How to Handle GET Requests with Access Tokens

apiapi-designdesigndesign-patterns

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.

Best Answer

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.

Related Topic