Simple, Secure PHP API Design

Question

I'm trying to design a secure RESTful API web service with as few moving parts as possible. I have some questions, and want to make sure my design is secure.

For the data transmission level of security, I'm going to use SSL/TLS to prevent interception, MITM, replay attacks, etc.

What that leaves is access control.

I have no desire to fight with OAuth. The reason being, I do not want to rely on a third party, and setting up local servers as the "authenticator" (or whatever OAuth calls it) isn't feasible.

So I was going to rely on a random token. Using a CSPRNG library (e.g., $token = random_bytes(32) in PHP), I plan to assign each username/password a $token, and store it in the DB using a password storage function (e.g., PBKDF2 or bcrypt). The token would also be retrieved by the user via SSL/TLS.

Then, on each request, the user will submit the token along with their JSON data. If the token they pass exists in the DB, the API call is processed.

This leaves me with quite a few questions:

• Can the token stay consistent (short of revocation or manual refresh), or should the token require being "refreshed" frequently? If so, what is the feasible way to handle that? Forcing the user to log into a web page to gain access to the new token seems to defeat the purpose of an API. This seems to indicate that it's at best a controversial point.
• What is the advantage of putting the token in an HTTP header (e.g., Authorization: Token SOMERANDOMVALUE) versus just stuffing it in the body of a JSON request? Either way, I'm not going to do anything with the request unless authentication succeeded. I was going to put it in the header anyway, but I was just curious.

Also, if anyone has any trustworthy sources to learn more about building secure API's, I'd really like to read them.

Answer 1

Can the token stay consistent (short of revocation or manual refresh), or should the token require being "refreshed" frequently? If so, what is the feasible way to handle that?

Even though if you don't want to implement OAuth I recommend to take a look at how the token handling is done in OAuth (Paragraph 1.5 and 1.5). With refresh tokens you can reduce the window of exposure if the bearer token got compromised while avoiding to ask the users to provide their credentials repeatedly.

What is the advantage of putting the token in an HTTP header (e.g., Authorization: Token SOMERANDOMVALUE) versus just stuffing it in the body of a JSON request?

AFAIK it's done because this header field is intended for this purpose. In practice it heavily depends on the use-case. Since there is the risk that the Authorization header is automatically send by some browsers which could introduce a CSRF vulnerability, it might be not desired to do it this way if you don't want to implement a CSRF-token. So adding the authentication information to the body or a custom header field is totally ok.

Have a look at the REST Security Cheat Sheet by OWASP for more tips on secure API design. Actually the entire site is interesting - it's a very good starting point for developing a better understanding for information security.