The Critical Shift: From Authentication (401) to Authorization (403)

API gateway shifting from 401 identity verification to 403 access control

(Figure 1: Identity verification vs. access control flow.)

In Part 2, we mastered the "Who are you?" check (Authentication). Now, we reach the "turn" in our series—shifting focus to the "What are you allowed to do?" check (Authorization)1.

This is a more subtle problem that requires a different debugging mindset. First, the good news: If you receive a 403 Forbidden, it means your authentication was successful2.

The Gateway knows who you are.
The token signature is valid.
The token has not expired3.

The problem lies in permissions. You successfully passed the first gate (Identity), but failed at the second gate (Access Control)4.

403 Forbidden: Practical Scenarios

Flowchart showing insufficient scopes and admin policies triggering 403 errors

(Figure 2: Two main triggers for 403 Forbidden errors.)

When you hit a 403, it’s usually due to one of two reasons: insufficient scope or administrative policy.

Scenario 1: Insufficient Scope (The Most Common 403)

Symptom: You try to POST to the /api/customers endpoint but receive a 403 Forbidden5.
Cause: Your Access Token's scope claim might only include customer:read, but this specific endpoint requires customer:write permission6.
Backend Collaboration: digiRunner works in concert with your backend here. For example, a Spring Boot backend might enforce this using @PreAuthorize("hasAuthority('SCOPE_customer:read')")7. The Gateway validates the token's legitimacy, while the backend enforces business logic based on the claims8.
Recommended Action: Paste your JWT into a debugger (like jwt.io) to inspect the scope claim, then cross-reference it with the API documentation9.

Scenario 2: Client Not Authorized (Management Policy)

Symptom: You receive a 403, even though your token scopes seem correct10.
Cause: This is a management-level policy. The digiRunner platform administrator may have configured the Gateway to prohibit this specific client (identified by client_id) from accessing this specific API, regardless of the user's token11.
Recommended Action: Contact your API administrator to grant authorization to your client application in the digiRunner admin console12.

The "Gotcha": Handling 400 Bad Request for ID Tokens

diagram comparing Access Token 401 errors with ID Token 400 errors.

(Figure 3: Expired tokens: 401 Unauthorized vs 400 Bad Request.)

This is a special edge case that often confuses developers. Sometimes, an authentication issue returns a 400 Bad Request instead of a 401.

Why?

According to digiRunner's documentation, an expired ID Token will return a 400 Bad Request13. This distinction highlights a deep understanding of the OIDC protocol:

An Access Token is a "bearer credential" for the Gateway (the API resource)14. If it's expired, the Gateway rejects the identity (401).
An ID Token is a "data object" for the client containing user info15.

If a backend service receives an ID Token and finds it expired, it treats it as invalid data syntax—hence, a "Bad Request"16. This also applies to forged or unverifiable ID Tokens17.

Debugging Quick Reference: The Cheat Sheet

debugging guide comparing Authentication failures and Authorization scope errors.

(Figure 4: API Gateway debugging: Authentication vs Authorization.)

To summarize the learnings from Part 2 and Part 3, here is the "Cheat Sheet" from the digiRunner documentation that simplifies the entire debugging flow18:

HTTP Code	Error Type	Meaning	Common Causes
401 Unauthorized	Authentication Failure	Invalid or missing credentials; identity cannot be confirmed.	Expired token, invalid signature, no token provided.
403 Forbidden	Authorization Failure	Identity confirmed, but lacks permission to access the resource.	Insufficient scope (scope claim) or lack of client role permissions.

This table is a direct manifestation of digiRunner's developer-centric design philosophy: simple, clear, and actionable19.

Conclusion: From Debugger to Architect

We have now mastered how to diagnose "all" JWT-related errors. We know what they are, why 401 happens, and how 403 and 400 differ20.

But how does the Gateway "know" a signature is invalid in the first place? How is this trust established securely across a distributed system? In our final part, we will go deeper and set up the JWS signing keys that make it all possible21.

FAQ:

1. What is the difference between 401 and 403 errors?

A: 401 error means authentication failed due to invalid credentials, while a 403 error means authentication succeeded but authorization failed.

2. What does a 403 Forbidden error mean?

A: It means the API Gateway verified your identity successfully, but you lack the required permissions to access the specific resource.

3. How do I fix a 403 insufficient scope error?

A: Inspect your JWT using a debugger like jwt.io, and cross-reference your token's scope claim with the API documentation.

4. Why do I get a 403 if my scopes are correct?

A: An administrator might have configured a management policy prohibiting your specific client application from accessing the API.

5. Why does an expired ID Token return a 400 error?

A: An ID Token is a data object, so if it expires, the backend treats it as invalid data syntax, returning 400.

6. What are the common causes of a 401 Unauthorized error?

A: 401 error is typically caused by an expired access token, an invalid signature, or no token being provided.

401 vs 403 Forbidden: Solving Authorization & ID Token Errors in digiRunner