Customize Security and Authentication

Scope Authentication

Global

Global security allows users to configure the SDK once and reuse the security configuration for all subsequent calls.

To use global security, define the security configuration in the security block at the root of the SDK.


paths:
  /drinks:
    get:
      operationId: listDrinks
      summary: Get a list of drinks.
      description: Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information.
      tags:
        - drinks
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: header
security: # Here
  - api_key: []

In the resulting SDK, the user can define the security configuration in the SDK's instantiation. It will then be automatically applied to all subsequent method calls without needing to be passed in as an argument:


import { SDK } from "speakeasy";
async function run() {
  const sdk = new SDK({
    apiKey: "<YOUR_API_KEY_HERE>",
  });
  const result = await sdk.drinks.listDrinks();
  // Handle the result
  console.log(result);
}
run();

Per-Operation Security

NOTE

Security Hoisting: In cases where global security is not defined, Speakeasy automatically hoists the most commonly occurring operation-level security to be considered global. This will simplify SDK usage.

Operation-specific security configuration overrides the default authentication settings for an endpoint. This is commonly used for operations that do not require authentication or are part of an authentication flow, such as obtaining a short-lived access token.

Define security within an operation's scope to apply operation-specific security:


paths:
  /drinks:
    get:
      operationId: listDrinks
      summary: Get a list of drinks.
      description: Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information.
      security: # Here
        - apiKey: []
      tags:
        - drinks
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: header
security:
  - {}

In the SDK, the user can pass in a specific security configuration as an argument to the method call:


import { SDK } from "speakeasy";
async function run() {
  const sdk = new SDK();
  const operationSecurity = "<YOUR_API_KEY_HERE>";
  const result = await sdk.drinks.listDrinks(operationSecurity);
  // Handle the result
  console.log(result);
}
run();

Environment Variables

A common pattern for setting global parameters and security options in an SDK is by using environment variables. Speakeasy supports this with environment variable prefixes. To enable this feature, set the envVarPrefix variable in the language section of the SDK's gen.yaml file.

Global parameters can then be provided via environment variables in the format {PREFIX}_{GLOBALNAME}. Documentation for this will be automatically included in the README.

Security options can also be set via environment variables if not provided directly to the SDK. For example, a security field like api_key can be set with the variable {PREFIX}_{API_KEY}.


const SDK = new SDK({
  apiKey: process.env["SDK_API_KEY"] ?? "",
});

NOTE

Note: In some cases, adding envVarPrefix may alter the structure of security options. Required global security will become optional to allow setting it via environment variables.

For details on enabling this feature during generation, see the language-specific gen.yaml configuration reference.