Why Choose JWT? Mastering Access and Refresh Tokens for Secure APIs

Why Use JWT

RESTful APIs and single‑page applications separate front‑end and back‑end, making traditional cookie‑session authentication cumbersome, especially in distributed or micro‑service architectures. Storing sessions in Redis adds operational cost. JSON Web Tokens (JWT) provide a stateless alternative for authentication and authorization.

JWT Use Cases

Authorization : The server signs (and optionally encrypts) a JWT and returns it to the client. The client includes the token in a specific HTTP header (or query/body). The server validates the token on each request to enforce access control.

Information Exchange : Using asymmetric keys, JWT can securely convey data between parties.

Access Token vs. Refresh Token

Access token is short‑lived (commonly 1–2 hours, sometimes as low as 15 minutes). It is presented to protected APIs to prove the caller’s identity.

Refresh token has a longer lifespan (typically ~30 days). It cannot access resources directly; its only purpose is to obtain a new access token when the current one expires, reducing the need for the user to re‑authenticate.

Login Endpoint

Clients obtain both tokens by posting credentials to the login API.

POST http://{{iot_domain}}/api/v1/user/login
{
  "username": "demo",
  "password": "e10dcc75"
}

Successful response:

{
  "code": 200,
  "msg": "请求成功",
  "data": {
    "access_token": "eyJ0eXAiOiJKV1QiL...",
    "refresh_token": "eyJ0eXAiOiJKV1sz..."
  }
}

Calling Protected APIs

Include the access token in the HTTP Authorization header.

Authorization: Bearer <access_token>

The server parses this header, extracts the user identity, and performs authorization.

Refresh Token Endpoint

When the access token expires, the client sends the refresh token to obtain a new access token.

GET http://{{iot_domain}}/api/v1/user/refresh
Authorization: Bearer <refresh_token>

Successful response returns a fresh access token (and optionally a new refresh token).

{
  "code": 200,
  "msg": "请求成功",
  "data": {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
  }
}

If the refresh token is still valid, the server issues a new access token.

Parameter Details

Login Request Parameters

username (string, required): User name, e.g., demo.

password (string, required): User password, e.g., e10dcc75.

Login Response Fields

code (int): Status code.

msg (string): Message describing the result.

data.access_token (string): JWT used for resource access.

data.refresh_token (string): JWT used to obtain a new access token.

Best Practices

Store tokens securely on the client (e.g., HttpOnly cookies or secure storage).

Keep the access token lifespan short to limit exposure if compromised.

Send the refresh token only to the dedicated refresh endpoint.

Use the exact header format Authorization: Bearer <token> with a single space between Bearer and the token.

Illustrations