Authentication documentation in Rest API - Cheat Sheet & Quick Revision

Recall & Review

beginner

What is authentication in the context of REST APIs?

Authentication is the process of verifying the identity of a user or system trying to access the API to ensure they are who they claim to be.

beginner

Name two common methods of authentication used in REST APIs.

Two common methods are Basic Authentication (using username and password) and Token-Based Authentication (using tokens like JWT).

intermediate

What is a JSON Web Token (JWT)?

A JWT is a compact, URL-safe token that contains claims to securely transmit information between parties and is often used for authentication in REST APIs.

intermediate

Why should API authentication documentation include error codes and messages?

Including error codes and messages helps developers understand why authentication failed and how to fix issues, improving the API usability.

beginner

What is the difference between authentication and authorization?

Authentication verifies who you are, while authorization determines what you are allowed to do after your identity is confirmed.

Which of the following is NOT a common authentication method for REST APIs?

A OAuth 2.0

B Token-Based Authentication

C FTP Authentication

D Basic Authentication

FTP Authentication is unrelated to REST APIs; OAuth 2.0, Basic, and Token-Based Authentication are common methods.

What does a JWT typically contain?

A User credentials in plain text

B Database connection details

C Only the user's password

D Claims about the user and metadata

JWTs contain claims about the user and metadata, securely encoded and signed.

In authentication documentation, what should be included to help developers handle failures?

A Error codes and descriptive messages

B Only success messages

C User personal data

D API server IP addresses

Error codes and descriptive messages help developers understand and fix authentication issues.

What is the main purpose of authentication in REST APIs?

A To encrypt data

B To verify the identity of the client

C To authorize access to resources

D To log API usage

Authentication verifies who the client is before granting access.

Which header is commonly used to send a token for authentication in REST APIs?

A Authorization

B Content-Type

C Accept

D User-Agent

The Authorization header is used to send tokens like Bearer tokens for authentication.

Explain the key components that should be included in authentication documentation for a REST API.

Think about what a developer needs to know to successfully authenticate.

Describe the difference between authentication and authorization in the context of REST APIs.

Focus on what each process does and their order.

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