Setting Up Authentication

Your User module now has well-designed endpoints with schemas and reusable components. But there's a critical piece missing: authentication. Without it, anyone could update or delete any user's data, which is a serious security risk.

In this article, we'll learn how to secure your API using Apidog's Security Schemes, focusing on implementing JWT (JSON Web Token) authentication for the User module. By the end, you'll know how to protect endpoints that require user authentication while keeping public endpoints accessible.

1. Why API Authentication Matters

Authentication verifies who is making the request—it ensures that only authorized users can access protected resources.

Without Authentication:

Anyone can modify or delete user data

No way to track who performed actions

Impossible to implement user-specific features

Security vulnerabilities and data breaches

With Authentication:

Only authenticated users can access protected endpoints

User actions can be tracked and audited

User-specific data and permissions can be enforced

Your API meets security standards

2. Common Authentication Methods

Different APIs use different authentication methods. Here are the most common:

1. API Key

How it works: A unique key is passed in the request (via header, query parameter, or cookie)

Example:

GET /users
X-API-Key: sk_live_abc123xyz456

Use case: Simple authentication for server-to-server communication

2. Bearer Token (JWT)

How it works: A token (often a JWT) is passed in the Authorization header

Example:

GET /users/usr_123
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Use case: Modern web and mobile apps, stateless authentication

What we'll use for the User module!

3. Basic Authentication

How it works: Username and password are encoded and sent in the Authorization header

Example:

GET /users
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Use case: Simple authentication, often for admin interfaces

4. OAuth 2.0

How it works: Industry-standard authorization framework with multiple grant types

Example:

GET /users
Authorization: Bearer <access_token>

Use case: Third-party app integrations, delegated access

3. Understanding Security Schemes in Apidog

In Apidog, Security Schemes are reusable authentication templates that follow the OpenAPI Specification.

What is a Security Scheme?

A Security Scheme defines:

The authentication method (API Key, Bearer Token, OAuth 2.0, etc.)

Where credentials are sent (header, query, cookie)

The parameter name (e.g., "Authorization" header)

But it doesn't include actual credentials (like the token value)—those are provided separately when testing.

Benefits:

Define once, use everywhere — Create the scheme once, apply to many endpoints

Separation of concerns — Template vs. actual credentials

Inheritance — Folders and endpoints can inherit security settings

OpenAPI compliant — Automatically generates proper OpenAPI security definitions

4. Creating a Security Scheme for the User Module

For the User module, we'll create a Bearer Token (JWT) security scheme.

Step 1: Navigate to Security Schemes

In your Apidog project, go to the left sidebar

Navigate to Components → Security Schemes

Click "New Security Scheme"

Step 2: Configure the Security Scheme

Name: JWT Authentication (or Bearer Token)

Type: Select "Bearer Token"

Format: Enter JWT (this is optional but adds clarity)

Your configuration should look like this:

Security Scheme Name: JWT Authentication

Type: Bearer Token

Bearer Format: JWT

Description: "JWT token-based authentication. Obtain token via POST /user/login"

Step 3: Save the Security Scheme

Click "Save" to create the security scheme.

Now you have a reusable JWT authentication template!

5. Applying Security Schemes to Endpoints

There are two ways to apply security schemes: at the folder level (for multiple endpoints) or at the endpoint level (for individual endpoints).

Method 1: Apply at Folder Level (Recommended)

Applying security at the folder level means all endpoints in that folder automatically inherit the authentication.

Steps:

Select the User Management folder (containing GET, PUT, DELETE /users endpoints)

In the right panel, go to the Auth tab

Select "Security Scheme" as the auth type

Choose "JWT Authentication" from the dropdown

Click "Save"

Now all endpoints in the User Management folder require JWT authentication!

Method 2: Apply at Endpoint Level

For individual endpoints, you can apply security directly:

Open an endpoint (e.g., PUT /users/{id})

In the Edit tab, scroll to the Request section

Under Authorization, select "Security Scheme"

Choose "JWT Authentication" from the dropdown

Click "Save"

Note: Endpoint-level settings override folder-level settings.

6. Which Endpoints Need Authentication?

For the User module, let's decide which endpoints need authentication:

Endpoints that REQUIRE authentication:

GET /users/{id} — View user profile (should only see your own or have permission)

PUT /users/{id} — Update user data (must be the user or admin)

DELETE /users/{id} — Delete user account (must be the user or admin)

POST /user/logout — Logout (must be logged in)

Endpoints that DON'T require authentication:

POST /users — Create user (signup is public)

POST /user/login — Login (can't be authenticated before logging in!)

But POST /user/login is special—it doesn't require auth, but it returns a token.

7. Implementing Authentication for the User Module

Let's apply JWT authentication to the User module endpoints.

Step 1: Apply to Protected Endpoints

For endpoints that need authentication:

GET /users/{id}:

Open the endpoint

Go to Edit → Request → Authorization

Select "Security Scheme" → "JWT Authentication"

PUT /users/{id}:

Apply the same JWT Authentication security scheme

DELETE /users/{id}:

Apply the same JWT Authentication security scheme

POST /user/logout:

Apply the same JWT Authentication security scheme

For public endpoints:

POST /users (Create user):

Leave Authorization as "No Auth" or "Inherit from parent" if parent is "No Auth"

POST /user/login:

Leave Authorization as "No Auth"

But configure the response to return a token

The login endpoint should return a JWT token in its response:

Open POST /user/login endpoint

Go to Response tab → 200 Success

Define the response schema:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2024-12-31T23:59:59Z",
  "user": {
    "id": "usr_3Oy2JIS7TMJgEXfM",
    "email": "jane.smith@example.com",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}

Schema structure:

token (string, required) — The JWT token

expiresAt (string, date-time, required) — When the token expires

user (object, optional) — User information

8. Key Takeaways

Setting up authentication in Apidog involves:

Security Schemes — Reusable authentication templates (JWT, API Key, OAuth 2.0, etc.)

Folder-level vs. Endpoint-level — Apply security globally or individually

Public vs. Protected — Not all endpoints need authentication

Login Endpoint — Public endpoint that returns a token in its response

OpenAPI Compliance — Security schemes export properly to OpenAPI format

Benefits:

Security — Protect sensitive operations

Consistency — Same authentication method across endpoints

Flexibility — Override security per endpoint when needed

Clear Documentation — Security requirements are clearly documented

What's Next?

Now that your User module has authentication configured, the next step is to ensure your API follows best practices and design guidelines. In the next article, we'll learn how to use Apidog's API Design Guidelines to maintain consistency and quality across your API design.

Continue with API Design Guidelines.

Setting Up Authentication

1. Why API Authentication Matters#

Without Authentication:#

With Authentication:#

2. Common Authentication Methods#

1. API Key#

2. Bearer Token (JWT)#

3. Basic Authentication#

4. OAuth 2.0#

3. Understanding Security Schemes in Apidog#

What is a Security Scheme?#

Benefits:#

4. Creating a Security Scheme for the User Module#

Step 1: Navigate to Security Schemes#

Step 2: Configure the Security Scheme#

Step 3: Save the Security Scheme#

5. Applying Security Schemes to Endpoints#

Method 1: Apply at Folder Level (Recommended)#

Method 2: Apply at Endpoint Level#

6. Which Endpoints Need Authentication?#

Endpoints that REQUIRE authentication:#

Endpoints that DON'T require authentication:#

7. Implementing Authentication for the User Module#

Step 1: Apply to Protected Endpoints#

Step 2: Leave Login and Signup Public#

Step 3: Configure Login Response to Return Token#

8. Key Takeaways#

What's Next?#

1. Why API Authentication Matters

Without Authentication:

With Authentication:

2. Common Authentication Methods

1. API Key

2. Bearer Token (JWT)

3. Basic Authentication

4. OAuth 2.0

3. Understanding Security Schemes in Apidog

What is a Security Scheme?

Benefits:

4. Creating a Security Scheme for the User Module

Step 1: Navigate to Security Schemes

Step 2: Configure the Security Scheme

Step 3: Save the Security Scheme

5. Applying Security Schemes to Endpoints

Method 1: Apply at Folder Level (Recommended)

Method 2: Apply at Endpoint Level

6. Which Endpoints Need Authentication?

Endpoints that REQUIRE authentication:

Endpoints that DON'T require authentication:

7. Implementing Authentication for the User Module

Step 1: Apply to Protected Endpoints

Step 2: Leave Login and Signup Public

Step 3: Configure Login Response to Return Token

8. Key Takeaways

What's Next?