auth0-springboot-api

Prerequisites

• Java 17+ and Spring Boot 3.2+

• Maven 3.6+ or Gradle 7+

• Auth0 API configured (not Application — must be API resource)

• If you don't have Auth0 set up yet, use the auth0-quickstart skill first

Quick Start Workflow

Agent instruction: If the user's prompt already provides Auth0 credentials (domain, audience), use them directly — skip the bootstrap script and credential questions. Only offer setup options when credentials are missing.

1. Install SDK

Gradle (build.gradle):

implementation 'com.auth0:auth0-springboot-api:1.0.0-beta.1'

Maven (pom.xml):

 
 com.auth0 
 auth0-springboot-api 
 1.0.0-beta.1 
 

2. Create Auth0 API

You need an API (not Application) in Auth0.

STOP — ask the user before proceeding.

Ask exactly this question and wait for their answer before doing anything else:

"How would you like to create the Auth0 API resource?

• Automated — I'll run Auth0 CLI scripts that create the resource and write the values to your application.yml automatically.

• Manual — You create the API yourself in the Auth0 Dashboard (or via auth0 apis create) and provide me the Domain and Audience.

Which do you prefer? (1 = Automated / 2 = Manual)"

Do NOT proceed to any setup steps until the user has answered. Do NOT default to manual.

If the user chose Automated, follow the Setup Guide for complete CLI scripts. The automated path writes application.yml for you — skip Step 3 below and proceed directly to Step 4.

If the user chose Manual, follow the Setup Guide (Manual Setup section). Then continue with Step 3.

Quick reference for manual API creation:

# Using Auth0 CLI
auth0 apis create \
 --name "My Spring Boot API" \
 --identifier https://my-springboot-api

Or create manually in Auth0 Dashboard → Applications → APIs

3. Configure application.yml

auth0:
 domain: "your-tenant.auth0.com"
 audience: "https://my-springboot-api"

Important: Domain must NOT include https://. The library constructs the issuer URL automatically.

Or use application.properties:

auth0.domain=your-tenant.auth0.com
auth0.audience=https://my-springboot-api

4. Configure Spring Security

@Configuration
@EnableMethodSecurity
public class SecurityConfig {

 @Bean
 SecurityFilterChain apiSecurity(
 HttpSecurity http,
 Auth0AuthenticationFilter authFilter
 ) throws Exception {
 return http
 .csrf(csrf -> csrf.disable())
 .sessionManagement(session ->
 session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
 .authorizeHttpRequests(auth -> auth
 .requestMatchers("/api/public").permitAll()
 .requestMatchers("/api/protected").authenticated()
 .requestMatchers("/api/admin/**").hasAuthority("SCOPE_admin")
 .anyRequest().authenticated())
 .addFilterBefore(authFilter, UsernamePasswordAuthenticationFilter.class)
 .build();
 }
}

5. Protect Endpoints

@RestController
@RequestMapping("/api")
public class ApiController {

 @GetMapping("/public")
 public ResponseEntity > publicEndpoint() {
 return ResponseEntity.ok(Map.of("message", "Public endpoint - no token required"));
 }

 @GetMapping("/protected")
 public ResponseEntity > protectedEndpoint(Authentication authentication) {
 Auth0AuthenticationToken token = (Auth0AuthenticationToken) authentication;
 return ResponseEntity.ok(Map.of(
 "user", authentication.getName(),
 "email", token.getClaim("email"),
 "scopes", token.getScopes()
 ));
 }
}

6. Test API

Agent instruction: After writing all code, verify the build succeeds:

./gradlew bootRun

or ./mvnw spring-boot:run. If build fails, diagnose and fix. After 5-6 failed attempts, use AskUserQuestion to get help.

Test public endpoint:

curl http://localhost:8080/api/public

Test protected endpoint (requires access token):

curl http://localhost:8080/api/protected \
 -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Get a test token via Client Credentials flow or Auth0 Dashboard → APIs → Test tab.

Common Mistakes

Mistake Fix Domain includes https:// Use your-tenant.auth0.com format only — no scheme prefix Audience doesn't match API Identifier Must exactly match the API Identifier set in Auth0 Dashboard Created Application instead of API in Auth0 Must create API resource in Auth0 Dashboard → Applications → APIs Missing addFilterBefore in SecurityConfig Auth0AuthenticationFilter must be added before UsernamePasswordAuthenticationFilter Using ID token instead of access token Must use access token for API auth, not ID token Checking scope claim in wrong format Scopes map to SCOPE_ prefixed authorities: use hasAuthority("SCOPE_read:data") Spring Boot env var binding Use AUTH0_DOMAIN not AUTH0_DOMAIN with underscores inside property names; Spring removes dashes and is case-insensitive