OAuth 2.0 authentication

Speakeasy supports the OAuth 2.0 security implementation, including type generation for OAuth schemas and in many cases the complete management of the token refresh flow. End users of Speakeasy SDKs don’t need to retrieve and manage access tokens manually.

API builders also have the option to leverage Speakeasy’s custom security schemes to implement custom OAuth flows that aren’t part of the standard OpenAPI specification.

This document covers the following types of OAuth 2.0 flows:

Other custom flows can be implemented using a combination of hooks and custom security schemes.

Client credentials flow

The client credentials flow is used to obtain an access token for API requests by prompting users for a client ID and client secret when instantiating the SDK. OAuth 2.0 defines several methods for building a request to the tokenUrl endpoint. Speakeasy supports the following authentication methods:

• client_secret_post (default method)
• client_secret_basic
• authorization-code (with hooks)
• Custom flows (with hooks and custom security schemes)

To enable the client credentials flow in the SDK:

• define type: oauth2 and flows: clientCredentials in your OpenAPI specification.
• add the following to the gen.yaml file:

client_secret_post

The client_secret_post method sends the client credentials in the request body as application/x-www-form-urlencoded form data. This is the default authentication method used by Speakeasy when no specific method is specified.

When using this method, the client ID and client secret are sent in the request body as form parameters:

client_secret_basic

The client_secret_basic method sends the client credentials in the Authorization header using the Basic authentication scheme. The client ID and client secret are combined with a colon separator, Base64-encoded, and sent in the header.

To use this method, add the x-speakeasy-token-endpoint-authentication: client_secret_basic extension to your OAuth security scheme:

When using this method, the client ID and client secret are sent in the Authorization header:

This method is preferred by some OAuth providers for security reasons, as it keeps credentials out of request bodies and server logs.

tokenUrl

The tokenUrl property in OAuth 2.0 flows can be specified in two formats:

1. A pathname (e.g., /auth/token)
2. An absolute URL (e.g., https://api.example.com/auth/token)

When a pathname is provided instead of an absolute URL, Speakeasy resolves it relative to the user’s configured server URL. This is particularly useful in environments where you have multiple server configurations and need the token endpoint to adapt accordingly.

For example, if your OpenAPI specification includes a pathname:

And the user has configured their server URL as https://api.example.com, the effective token URL will be https://api.example.com/clientcredentials/token.

Alternatively, you can specify an absolute URL:

This feature allows for more flexible authentication configurations across different environments without requiring changes to the OpenAPI specification.

additional properties

To provide additional properties to the tokenUrl, you need to use the x-speakeasy-token-endpoint-additional-properties extension.

For example, to include an audience parameter we need to modify our OpenAPI specification like this:

Example OpenAPI configuration

Here’s a complete example showing how to configure OAuth client credentials flow in your OpenAPI specification:

Resource Owner Password Credentials flow

Also known informally as OAuth 2.0 Password flow.

Resource Owner Password Credentials (ROPC) flow is designed for obtaining access tokens directly in exchange for a username and password.

Below is an example of how ROPC Flow is configured in openapi.yaml. You’ll note that oauth2 security scheme is linked to the listProducts operation and that the scope products:read is required by the listProducts operation.

To enable OAuth 2.0 ROPC flow in the SDK, add the following to the gen.yaml file:

When making a call using this flow, the SDK security is configured with these parameters:

Below are usage examples in supported languages:

It is also possbile to bypass token retrievals by passing an explicit token to the SDK object:

Authorization code flow

Authorization code flows can vary in implementation, but there are typically some secret values that need to be passed during the code token exchange.

The format for the secret values can also vary but a very common format is:

• <Term> often being Basic or Bearer
• The following string being some format of Client ID and Client Secret, combined with a : and then base64 encoded.

To allow for any possible formatting Speakeasy offers support for Hooks, these hooks allow you to alter a request before it is sent to the server.

For this example we will be using the names id and secret, but you can use any names you like.

First we will define a custom security schema, documentation for that can be found here

This security schema will then be applied to our OAuth token exchange endpoint.

This custom security schema allows us to supply the Id and Secret needed for the token exchange directly to that method, and generate the unique header value needed with a hook.

Next we add the hook to generate that header.

Now that the hook is added, when you are using the SDK to acquire an OAuth token, you can pass in the values and the hook will generate the special header for you.

Custom refresh token flow

To enable custom OAuth refresh token handling, implement security callbacks along with additional configuration outside the OpenAPI spec.

Step 1: Define OAuth security in the OpenAPI spec

Step 2: Add a callback function to the SDK

Add a file called oauth with the appropriate file extension for the programming language (for example, oauth.ts for TypeScript, oauth.py for Python, oauth.go for Go, and so on) to implement OAuth token exchange logic.

Step 3: Pass the callback function in SDK instantiation

Update the README to show how to pass the callback function when instantiating the SDK:

OAuth 2.0 scopes

Global security with OAuth 2.0 scopes

The available scopes for the OAuth 2.0 scheme can be listed in the scopes property when defining the security component.

The following OpenAPI definition then applies global OAuth 2.0 scopes:

In this configuration the SDK automatically requests the read and write scopes for all operations. This is useful for APIs where most endpoints share the same level of access. When making a request, the SDK checks whether the token contains the required scopes for the operation. If the token lacks the necessary scopes or has expired, a new token is requested with the correct scopes.

Per-operation OAuth 2.0 scheme

For more control over specific API operations, OAuth2 security schemes can be applied to specific operations only:

Per-operation OAuth 2.0 scopes

In the following example:

• the read scope is applied globally as it is defined in the root-level security section.
• the write scope is required for the updateOrder operation.
• the admin scope is available in the scopes property but not actually used by any operation.