[OPIK-8252] [BE] feat: Report expires_at from MCP OAuth token introspection

apps/opik-backend/src/main/java/com/comet/opik/domain/mcpoauth/McpOAuthService.java

@@ -183,6 +183,7 @@ public Optional<ValidatedToken> validateAccessToken(@NonNull String token) {
                     .workspaceId(row.workspaceId())
                     .workspaceName(row.workspaceName())
                     .resource(row.resource())
+                    .expiresAt(row.expiresAt())
                     .build());
         });
     }

apps/opik-backend/src/main/java/com/comet/opik/domain/mcpoauth/ValidatedToken.java

@@ -5,12 +5,21 @@
 import com.fasterxml.jackson.databind.annotation.JsonNaming;
 import lombok.Builder;
 
+import java.time.Instant;
+
+/**
+ * What the introspection endpoint ({@code POST /opik/auth-oauth}) tells a resource server about a live access
+ * token. {@code expiresAt} is the token row's expiry: opik-mcp caches a "valid" answer until then instead of
+ * re-asking on a fixed timer, which closes the window in which an expired token is still forwarded (OPIK-8252).
+ * Additive — resource servers that predate the field ignore it.
+ */
 @Builder(toBuilder = true)
 @JsonInclude(JsonInclude.Include.NON_NULL)
 @JsonNaming(PropertyNamingStrategies.SnakeCaseStrategy.class)
 public record ValidatedToken(
         String userName,
         String workspaceId,
         String workspaceName,
-        String resource) {
+        String resource,
+        Instant expiresAt) {
 }

apps/opik-backend/src/test/java/com/comet/opik/api/resources/oauth/OAuthValidateTokenResourceTest.java

@@ -18,6 +18,9 @@
 import org.junit.jupiter.params.provider.NullSource;
 import org.junit.jupiter.params.provider.ValueSource;
 
+import java.time.Duration;
+import java.time.Instant;
+import java.time.temporal.ChronoUnit;
 import java.util.Optional;
 import java.util.UUID;
 
@@ -94,6 +97,7 @@ void acceptsValidToken(String schemePrefix) {
                 .workspaceId(UUID.randomUUID().toString())
                 .workspaceName(RandomStringUtils.secure().nextAlphanumeric(10))
                 .resource("http://localhost/api/v1/mcp/%s".formatted(RandomStringUtils.secure().nextAlphanumeric(8)))
+                .expiresAt(Instant.now().plus(Duration.ofHours(1)).truncatedTo(ChronoUnit.MILLIS))
                 .build();
         when(mcpOAuthService.validateAccessToken(ACCESS_TOKEN)).thenReturn(Optional.of(validated));
 
@@ -102,4 +106,25 @@ void acceptsValidToken(String schemePrefix) {
             assertThat(response.readEntity(ValidatedToken.class)).isEqualTo(validated);
         }
     }
+
+    @Test
+    @DisplayName("reports the token expiry as an ISO-8601 expires_at so resource servers can cache until then")
+    void reportsExpiresAtOnTheWire() {
+        // opik-mcp caches a "valid" answer until this instant (OPIK-8252); an
+        // epoch number or a camelCase key would silently fall back to its TTL.
+        var expiresAt = Instant.parse("2026-09-04T10:15:30.123Z");
+        var validated = ValidatedToken.builder()
+                .userName(RandomStringUtils.secure().nextAlphanumeric(10))
+                .workspaceId(UUID.randomUUID().toString())
+                .workspaceName(RandomStringUtils.secure().nextAlphanumeric(10))
+                .resource("http://localhost/api/v1/mcp")
+                .expiresAt(expiresAt)
+                .build();
+        when(mcpOAuthService.validateAccessToken(ACCESS_TOKEN)).thenReturn(Optional.of(validated));
+
+        try (Response response = validate("Bearer " + ACCESS_TOKEN)) {
+            assertThat(response.getStatus()).isEqualTo(Response.Status.OK.getStatusCode());
+            assertThat(response.readEntity(String.class)).contains("\"expires_at\":\"2026-09-04T10:15:30.123Z\"");
+        }
+    }
 }