Introducing Multiple Authentication Scheme Support

We have added support for generating SDKs and documentation for API definitions that use Multiple Authentication schemes.

Details

We are excited to announce that you can now define multiple security schemes in your API references and authorize your API Calls using multiple combinations of your security schemes through our newly designed authorization section in your API Playground. This release also brings in a new interface for setting up authentication credentials in your SDK's client.

What's New?

We can define multiple authentication schemes in components of an OpenAPI specification file like the following:

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    apiToken:
      type: apiKey
      name: token
      in: header

The above components define two different security schemes. These security components can either be applied to the whole specification globally or to an individual endpoint locally like the following example. You can follow this documentation to learn more about applying security in OpenAPI specification.

AND Case

The following security definition represents the basicAuth AND apiToken combination:

security:
  - basicAuth: []
    apiToken: []

OR Case

The following security definition represents the basicAuth OR apiToken combination:

security:
  - basicAuth: []
  - apiToken: []

Previously, we were only selecting the first defined security scheme and applying it globally for all the endpoints. We are now introducing multiple authentication support across our tooling. This brings major improvements and enhancements in the following areas:

• SDKs and documentation for all languages
• Getting Started Guides for SDKs
• API Code Playground in the API Portal

Multiple Authentication in SDKs

With Multiple Authentication Support our SDKs now can apply more than one security scheme to any request. Our SDKs can also now distinguish between the AND or OR combination of multiple security definitions.

Auth Validation Errors

Our SDKs now can check the combination type i.e. AND or OR of the security definitions for each request with an abstraction layer for the SDK user. Whenever an endpoint method call is invoked we check if that endpoint requires more authentication credentials than the ones specified in the client configurations. We will throw an AuthValidationException like the one following:

AuthValidationException: The following authentication credentials were required:
-> Missing required auth credential: token
-> Missing required auth credential: api-key

Catching such errors on the client side will also save network costs and help the developers show relevant error messages for their application users.

Multiple Auth Configurations

We came up with a new simpler interface to set up authentication credentials in our SDKs for all languages. You can now set authentication credentials directly into your client instance. That authorized client can later be used to perform any number of API Calls directly.

The credentials for each security scheme are now grouped into one instance, keeping the client initialization clean and descriptive. Let us have a look at what's new in the client initialization for all languages.

To create an authorized client instance for our SDKs, there are two different flows for Single or Multiple Authentication. Single authentication credentials can be set directly into the client. If your API uses multiple security flows you would then be able to set the credentials using a grouped instance for each security flow as shown in the following example. We are also deprecating the existing single authentication flow. Please follow the deprecated method documentation and use the new authentication setter.

TypeScript

Single Authentication

const client = new Client({
  basicAuthUsername: "Username", // Deprecated
  basicAuthPassword: "Password", // Deprecated
  basicAuthCredentials: {
    username: "Username",
    password: "Password",
  },
});

Multiple Authentication

const client = new Client({
  basicAuthCredentials: {
    username: "Username",
    password: "Password",
  },
  apiKeyCredentials: {
    token: "Token",
  },
});

Java

Single Authentication

SdkClient client = new SdkClient.Builder()
    .basicAuthCredentials("Username", "Password") // Deprecated
    .basicAuthCredentials(
        new BasicAuthModel.Builder(
            "Username",
            "Password"
        )
        .build())
    .build();

Multiple Authentication

SdkClient client = new SdkClient.Builder()
    .basicAuthCredentials(
        new BasicAuthModel.Builder(
              "Username",
              "Password"
        )
        .build())
    .apiKeyCredentials(
        new ApiKeyModel.Builder(
            "Token"
        )
        .build())
    .build();

Python

Single Authentication

client = SdkClient(
    basic_auth_user_name='BasicAuthUserName', # Deprecated
    basic_auth_password='BasicAuthPassword', # Deprecated
    basic_auth_credentials=BasicAuthCredentials(
        username='Username',
        password='Password'
    )
)

Multiple Authentication

client = SdkClient(
    basic_auth_credentials=BasicAuthCredentials(
        username='Username',
        password='Password'
    ),
    api_key_credentials=ApiKeyCredentials(
        token='Token'
    )
)

PHP

Single Authentication

$client = SdkClientBuilder::init()
    ->basicAuthUserName('BasicAuthUserName') // Deprecated
    ->basicAuthPassword('BasicAuthPassword') // Deprecated
    ->basicAuthCredentials(
        BasicAuthCredentialsBuilder::init(
            'Username',
            'Password'
        )
    )
    ->build();

Multiple Authentication

$client = SdkClientBuilder::init()
    ->basicAuthCredentials(
        BasicAuthCredentialsBuilder::init(
            'Username',
            'Password'
        )
    )
    ->apiKeyCredentials(
        ApiKeyCredentialsBuilder::init(
            'Token'
        )
    )
    ->build();

.NET

Single Authentication

SdkClient client = new SdkClient.Builder()
    .BasicAuthCredentials("BasicAuthUserName", "BasicAuthPassword") // Deprecated
    .BasicAuthCredentials(
        new BasicAuthModel.Builder(
            "Username",
            "Password"
        )
        .Build())
    .Build();

Multiple Authentication

SdkClient client = new SdkClient.Builder()
    .BasicAuthCredentials(
        new BasicAuthModel.Builder(
            "Username",
            "Password"
        )
        .Build())
    .ApiKeyCredentials(
        new ApiKeyModel.Builder(
            "Token"
        )
        .Build())
    .Build();

Ruby

Single Authentication

client = Sdk::Client.new(
  basic_auth_user_name: 'BasicAuthUserName', # Deprecated
  basic_auth_password: 'BasicAuthPassword', # Deprecated
  basic_auth_credentials: BasicAuthCredentials.new(
    username: 'Username',
    password: 'Password'
  )
)

Multiple Authentication

client = Sdk::Client.new(
  basic_auth_credentials: BasicAuthCredentials.new(
    username: 'Username',
    password: 'Password'
  ),
  api_key_credentials: ApiKeyCredentials.new(
    token: 'Token',
  )
)

Go

client := NewClient(
  CreateConfiguration(
    WithBasicAuthCredentials(
      NewBasicAuthCredentials(
        "Username",
        "Password",
      ),
    ),
    WithApiKeyCredentials(
      NewApiKeyCredentials(
        "Token",
      ),
    ),
  ),
)

Exclude Deprecated Single Authentication Flow

As you can see from the above code snippets, we have now deprecated the existing flow to set up a client with authentication credentials if the API specification has a single security scheme defined. The older flow is kept in the generated SDK to avoid breaking changes for our existing customers. So if you are new to the APIMatic and looking to exclude the deprecated code from your SDKs, set the AddSingleAuthDeprecatedCode codegen setting to false.

info:
  x-codegen-settings:
    AddSingleAuthDeprecatedCode: false

However, if you are already using APIMatic and onboarded all of your SDK users to the new authentication flow, feel free to remove the deprecated code from SDKs. You can read more about AddSingleAuthDeprecatedCode CodegenSetting on the changes it can apply to your SDK.

UI Refinement and Accessibility Upgrade

The authentication section has been relocated from the configuration area within the code samples to a prominent position above the API playground. The UI has also been revamped with an elegant design, ensuring a visually appealing and user-friendly experience. This reorganization along with the UI update makes the authentication section more accessible and visible.

Before

After

We have presented the AND security definitions in a clear and vertical layout, stacking one below the other. Meanwhile for the OR security definitions switchable pills, similar to those used in the API playground, are incorporated in the UI. We have ensured that the design ensures a consistent and familiar experience for users, promoting ease of use and reducing the learning curve.

AND Case

OR Case

Improvements in ReadMe and Step-By-Step Guide

We have updated the SDK READMEs. Previously, we showed the API client initialization and documentation for only a single security scheme defined in the spec (OAuth2 Client Credentials Grant in this case).

Now, we show the API client initialization for all the security schemes and have split the documentation of each security scheme into its markdown file.

Before

After

The documentation for each security scheme has been moved to the doc/auth/ folder. The following is from doc/auth/oauth-2-client-credentials-grant.md.

We have also updated the step-by-step guide on the portal similarly. In this case, all auth documentation is on a single page.

Before

After

Opt Out of Multiple Authentication

As we have discussed we were only selecting the first defined security scheme and applying it globally for all the endpoints before the introduction of this feature. If you happen to have multiple security schemes defined in your API specifications until today. You might find the interface of your generated SDK switched to the new multiple authentication design after regeneration. This will bring breaking changes to your SDKs. To avoid such breaking changes you can opt out of this feature using the following CodegenSetting:

info:
  x-codegen-settings:
    DisableMultipleAuth: true

However, we recommend you should stick with the newly improved multiple-authentication flow of your SDKs because this flag will be deprecated eventually. It is the true representation of your API specification. We have enabled MultipleAuth by default. You can read more about DisableMultipleAuth CodegenSetting on the changes it can apply to your SDK.