What this post covers

In this short post we are going to look at where the bearer token belongs. If you already know the five request verbs, and you can name Content-Type, Accept, and Authorization, you are ready.

This is for juniors. We will put the blog in the body, put the token in the Authorization header, catch the mistake of saving that token on the post, name the one body that may carry a token, and separate that from an email activation token. You do not need to know how tokens are made. When you finish, you can say why the token stays in the header.

The body is the blog. The token is about the request.

The body is the blog

POST /api/blogs creates a blog. You send that blog in the body, as JSON. A title, and the text. Content-Type: application/json tells the server to read that body as JSON.

POST /api/blogs
Content-Type: application/json

{
  "title": "Hello",
  "text": "A short post"
}

That JSON is the blog. It is not a pocket for the token.

The token stays in the header

The token is not part of that blog. It proves who is asking. That proof goes in the Authorization header: Authorization: Bearer, then the token.

A common junior mistake is to drop the token into the JSON, next to the title. The app builds the blog from that body, so the token can be saved on the post. The next GET can hand it back.

In the JSON

{ "title": "Hello", "text": "A short post", "token": "abc123" }

On the header

Authorization: Bearer abc123

Body stays title and text.

Two cream papers on a dark table. The left page has a brass token pressed into the middle. The right envelope has the token on its flap. Labels: In the JSON, On the header. — The token sits on the letterhead, not pressed into the page.

There is a second reason. GET and DELETE often have no body. You still have to prove who you are. A token inside JSON is not there. The Authorization header is. DELETE /api/blogs/42 still sends Authorization: Bearer, and it sends no body.

The header carries the token even when the request has no body.

One limit

A body can be JSON. Ours is. The bearer rules in RFC 6750 (2012) also allow a form body to carry a token, and only as a fallback, when a client cannot set the Authorization header. That method is not for GET, and the body must be a form, not JSON.

A form is a different body. It is not your blog JSON. On our blog requests the token still stays in the header.

Do not copy the form fallback onto this API. The blog body stays JSON. The token stays in Authorization.

A different token

Registration is a different job. The server emails a one-time token inside a link, because a mail app can only open a URL:

https://example.com/activate?token=abc123

That is the one place this token belongs in a URL. The activation page then sends its own request. The token is the body. It is not in the API URL, and it is not in the Authorization header.

POST /api/auth/activate
Content-Type: application/json

{ "token": "abc123" }

An Authorization token is for a verified active user only. This request is what verifies them.

What you can say

You can hear the same path in the companion tip, Token in the header. The three common headers live in Request headers.

The body is the blog. The token is about the request, so it stays in the authorization header.

Token in the header

More from the blog.

Request headers

Five request verbs