Authentication documentation in Rest API - Step-by-Step Execution

Concept Flow - Authentication documentation

Client sends credentials

↓

Server verifies credentials

↓

Issue token

↓

Client uses token for requests

↓

Server validates token on each request

The client sends credentials to the server, which checks them. If valid, the server issues a token. The client uses this token for future requests, and the server validates it each time.

Execution Sample

Rest API

POST /login
Body: {"user":"alice", "pass":"1234"}
Response: {"token":"abc123"}

GET /data
Header: Authorization: Bearer abc123
Response: {"data": "secret"}

Client logs in with username and password, receives a token, then uses that token in the Authorization header to access protected data.

Execution Table

Step	Action	Input	Server Response	Client State
1	Send login request	{"user":"alice", "pass":"1234"}	200 OK, {"token":"abc123"}	Has token abc123
2	Send data request with token	Header: Authorization: Bearer abc123	200 OK, {"data": "secret"}	Token used for access
3	Send data request with invalid token	Header: Authorization: Bearer wrongtoken	401 Unauthorized	Access denied
4	Send data request without token	No Authorization header	401 Unauthorized	Access denied

💡 Requests stop when client has valid token or is denied access due to invalid/missing token.

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4
token	null	abc123	abc123	abc123	abc123
access_granted	false	true	true	false	false

Key Moments - 2 Insights

Why does the server reject requests without a token or with a wrong token?

The server checks the Authorization header for a valid token. If missing or invalid (see execution_table rows 3 and 4), it returns 401 Unauthorized to protect data.

How does the client use the token after login?

After receiving the token in step 1, the client includes it in the Authorization header for future requests (step 2), allowing access to protected resources.

Visual Quiz - 3 Questions

Look at the execution table, what is the server response when the client sends a valid token?

A 401 Unauthorized

B 500 Internal Server Error

C 200 OK with data

D Redirect to login

💡 Hint

Check execution_table row 2 under 'Server Response'

At which step does the client receive the token?

A Step 1

B Step 2

C Step 3

D Step 4

💡 Hint

Look at execution_table row 1, server response includes the token

If the client sends no Authorization header, what happens according to the execution table?

A Access granted

B Server returns 401 Unauthorized

C Server returns 200 OK

D Server ignores the request

💡 Hint

See execution_table row 4, server response is 401 Unauthorized

Concept Snapshot

Authentication in REST API:
- Client sends credentials (e.g., username/password) to /login
- Server verifies and returns a token if valid
- Client includes token in Authorization header for protected requests
- Server validates token on each request
- Invalid or missing token causes 401 Unauthorized response

Full Transcript

Authentication in REST APIs works by the client sending login credentials to the server. The server checks these credentials and if they are correct, it sends back a token. The client then uses this token in the Authorization header for future requests to access protected data. The server checks the token each time and only allows access if the token is valid. If the token is missing or wrong, the server responds with 401 Unauthorized to keep data safe.

Practice

1. What is the main purpose of authentication in a REST API?

easy

A. To speed up the API response time

B. To encrypt the data sent over the network

C. To format the API response in JSON

D. To confirm the identity of a user or client

Solution

1. Step 1: Understand authentication role

   Authentication is about confirming who the user or client is.

2. Step 2: Differentiate from other API functions

   Encryption, speed, and formatting are different concerns, not authentication.

3. Final Answer:

   To confirm the identity of a user or client -> Option D

4. Quick Check:

   Authentication = Confirm identity [OK]

Hint: Authentication means confirming who you are [OK]

Common Mistakes:

• Confusing authentication with encryption
• Thinking authentication speeds up API
• Mixing authentication with data formatting

2. Which of the following is the correct way to send an authentication token in a REST API request header?

easy

A. Token: <token>

B. Auth-Token: <token>

C. Authorization: Bearer <token>

D. Access: <token>

Solution

1. Step 1: Recall standard header format

   The standard way to send tokens is using the 'Authorization' header with 'Bearer' prefix.

2. Step 2: Compare options

   Only Authorization: Bearer <token> uses the correct 'Authorization: Bearer <token>' format.

3. Final Answer:

   Authorization: Bearer <token> -> Option C

4. Quick Check:

   Token header = Authorization: Bearer [OK]

Hint: Use 'Authorization: Bearer' to send tokens [OK]

Common Mistakes:

• Using wrong header names like 'Token' or 'Access'
• Omitting 'Bearer' keyword before token
• Placing token in URL instead of header

3. Given this API request code snippet, what will be the output if the token is missing?

fetch('https://api.example.com/data', {
  headers: { 'Authorization': 'Bearer ' }
})
.then(response => response.status)
.then(status => console.log(status));

medium

A. 401

B. 404

C. 500

D. 200

Solution

1. Step 1: Understand missing token effect

   When the token is missing or empty, the server usually rejects the request as unauthorized.

2. Step 2: Identify HTTP status code for unauthorized

   The standard status code for unauthorized access is 401.

3. Final Answer:

   401 -> Option A

4. Quick Check:

   Missing token = 401 Unauthorized [OK]

Hint: Missing token causes 401 Unauthorized error [OK]

Common Mistakes:

• Assuming missing token returns 200 OK
• Confusing 401 with 404 Not Found
• Thinking server returns 500 error

4. Identify the error in this authentication header usage:

headers: {
  'Authorization': 'BearerToken abc123'
}

medium

A. Missing space between 'Bearer' and token

B. Token should be in lowercase

C. Authorization header should be 'Auth' instead

D. Token must be sent as a query parameter

Solution

1. Step 1: Check Authorization header format

   The correct format requires a space between 'Bearer' and the token string.

2. Step 2: Verify the given header

   The header uses 'BearerToken' without space, which is incorrect.

3. Final Answer:

   Missing space between 'Bearer' and token -> Option A

4. Quick Check:

   Bearer and token need space [OK]

Hint: Add space after 'Bearer' before token [OK]

Common Mistakes:

• Writing 'BearerToken' as one word
• Using wrong header name like 'Auth'
• Sending token in URL instead of header

5. You want to secure an API endpoint so only authenticated users can access it. Which combination is best practice for this in your API documentation?

hard

A. Allow clients to send username and password in every request body

B. Require clients to send a valid token in the 'Authorization: Bearer <token>' header for access

C. Use IP address filtering to allow only certain clients

D. Send the token as a URL parameter for easy access

Solution

1. Step 1: Identify secure token usage

   Best practice is to require a valid token in the 'Authorization' header to confirm identity securely.

2. Step 2: Evaluate other options

   Sending username/password every time is insecure; IP filtering is limited; URL tokens risk exposure.

3. Final Answer:

   Require clients to send a valid token in the 'Authorization: Bearer <token>' header for access -> Option B

4. Quick Check:

   Token in Authorization header = secure access [OK]

Hint: Use Authorization header with token, not URL or body [OK]

Common Mistakes:

• Sending credentials in every request body
• Exposing tokens in URL parameters
• Relying only on IP filtering for security