Feature Request: Flatten Individual Security Fields in SDK Constructor

[leggetter]

Discussion: Flatten Individual Security Fields in SDK Constructor

Problem

When using flattenGlobalSecurity: true with multiple security schemes, Speakeasy flattens the security object to the constructor level, but still requires a nested structure:

// Current behavior with flattenGlobalSecurity: true
const sdk = new Outpost({
  security: {
    adminApiKey: "...",
    tenantJwt: "..."
  }
});

Desired Behavior

We want individual security fields to be flattened to the top level of the constructor:

// Desired behavior
const sdk = new Outpost({
  adminApiKey: "...",
  tenantJwt: "..."
});

Why This Matters

1. Better Developer Experience: Eliminates unnecessary nesting when the resource being operated on is already clear from the prefix (e.g., destinations.create doesn't need TenantDestination appended)
2. Consistency: Matches the pattern we use for method names where we prefer shorter, clearer names
3. Reduced Boilerplate: Less nested object creation in common use cases

Current Limitation

Speakeasy's flattenGlobalSecurity: true doesn't fully flatten individual security fields when multiple security schemes are present. It flattens the security object itself to the constructor, but keeps the fields nested within it.

Potential Solutions

Option 1: Custom Code Regions (Explored)

We've explored using custom code regions to manually flatten security fields:

• ✅ Works technically
• ❌ Requires maintaining custom code for each SDK (TypeScript, Python, Go)
• ❌ Manual updates after each SDK regeneration
• ❌ Risk of losing changes if custom code regions aren't preserved correctly

Option 2: OpenAPI Overlays

• Could potentially modify the Security component definition
• Unclear if this would affect constructor signature generation
• Needs investigation

Option 3: Accept Current Behavior

• Keep using nested security object
• Simpler maintenance
• Less ideal DX

OpenAPI Spec Context

Our spec defines multiple security schemes at the root level:

security:
  - AdminApiKey: []
  - TenantJwt: []

components:
  securitySchemes:
    AdminApiKey:
      type: http
      scheme: bearer
    TenantJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT

Configuration

We currently have:

• flattenGlobalSecurity: true in our gen.yaml
• hoistGlobalSecurity: true in generation config
• Multiple security schemes defined globally

Discussion Points

1. Is the DX improvement worth the maintenance overhead? Custom code regions would need to be maintained across all three SDKs (TypeScript, Python, Go).

2. Should we wait for Speakeasy? This could be a feature request to Speakeasy, but timeline is uncertain.

3. Alternative approaches? Are there other ways to achieve this without custom code regions?

4. Priority: How important is this compared to other DX improvements?

Related

• This relates to our method naming preferences where we use overlays to shorten method names (e.g., destinations.create instead of destinations.createTenantDestination)
• Similar DX improvement goal: reduce unnecessary verbosity in the API

[alexbouchardd]

Nitpick but I'd use apiKey: "..." over adminApiKey