Authentication

SDKs generated by liblab support a range of authentication methods to access your APIs. This guide shows how to configure your SDK generation depending on the authentication method you use. You can support multiple authentication methods in a single SDK. The different authentication types are set in the config file.

liblab also supports refresh tokens for authentication.

Authentication types

Authentication type	Config file value	Description
API key	apikey	API key authentication
Basic authentication	basic	Basic authentication with a user name and password
Bearer token	bearer	Bearer token authentication

You can also leverage hooks to add custom authentication to your SDK, or to modify the authentication process.

API Key

If your API needs an API key, this can be sent in a header with every request. To configure API key authentication, set the following in your config file:

{
  "auth": [
    "apikey"
  ]
}

By default the X_API_KEY header is used to send the API key, but this can be configured using the config file, or set in code when using the SDK:

{
  ...
  "customizations": {
    "authentication": {
      "apiKey": {
        "header": "MY_CUSTOM_APIKEY_HEADER"
      }
    },
  ...
}

The API key is set when you initialize the SDK:

TypeScript

export class ExcitingSoda {
  constructor(apiKey: string = '', apiKeyHeader: string = 'X-API-KEY') {}
  ...
}

import { ExcitingSoda } from 'excitingsoda';

const sdk = new ExcitingSoda(process.env.EXCITINGSODA_API_KEY);

Python

class ExcitingSoda:
    def __init__(self, api_key="", api_key_header="X-API-KEY", environment=Environment.DEFAULT) -> None:

from os import getenv
from excitingsoda import ExcitingSoda

sdk = ExcitingSoda(getenv("EXCITINGSODA_API_KEY"))

Java

public class ExcitingSoda {
  public ExcitingSoda(String apiKey) {}
  ...
}

import soda.exciting.ExcitingSoda;

ExcitingSoda client = new ExcitingSoda(System.getenv("EXCITINGSODA_API_KEY"));

If your API requires the API key as a query parameter instead of in a header, you can configure this using hooks as described in Customize your SDK with hooks tutorial.

Basic authentication

If your API uses basic authentication, the user name and password can be sent as a base64 encoded string in the Authorization header with every request. To configure basic authentication, set the following in your config file:

{
  "auth": [
    "basic"
  ]
}

This will send the provided user name and password encoded in base64 in the Authorization header:

"Authorization": "Basic bWFkZSB5b3UgbG9vaw=="

The user name and password are set when you initialize the SDK:

TypeScript

export class ExcitingSoda {
  constructor(username: string = '', password: string = '') {}
  ...
}

import { ExcitingSoda } from 'excitingsoda';

const sdk = new ExcitingSoda(process.env.EXCITINGSODA_USERNAME, process.env.EXCITINGSODA_PASSWORD);

Python

class ExcitingSoda:
    def __init__(self, username: str = "", password: str = "", environment=Environment.DEFAULT) -> None:

from os import getenv
from excitingsoda import ExcitingSoda

sdk = ExcitingSoda(getenv("EXCITINGSODA_USERNAME"), getenv("EXCITINGSODA_PASSWORD"))

Java

public class ExcitingSoda {
  public ExcitingSoda(String username, String password) {}
  ...
}

import soda.exciting.ExcitingSoda;

ExcitingSoda client = new ExcitingSoda(System.getenv("EXCITINGSODA_BASIC_USERNAME"),
                                       System.getenv("EXCITINGSODA_BASIC_PASSWORD"));

Bearer token

If your API uses a bearer token, this can be sent in the Authorization header with every request. To configure bearer token authentication, set the following in your config file:

{
  "auth": [
    "bearer"
  ]
}

By default the token is prefixed with Bearer in the Authorization header:

"Authorization": "Bearer Q3VyaW91cyBhcmVuJ3QgeW91IQ=="

This can be customized in the config file:

{
  ...
  "customizations": {
    "authentication": {
      "access": {
        "prefix": "MY_CUSTOM_PREFIX"
      }
    },
  ...
}

Giving:

"Authorization": "MY_CUSTOM_PREFIX Q3VyaW91cyBhcmVuJ3QgeW91IQ=="

The bearer token is set when you initialize the SDK:

TypeScript

export class ExcitingSoda {
  constructor(accessToken: string = '') {}
  ...
}

import { ExcitingSoda } from 'excitingsoda';

const sdk = new ExcitingSoda(process.env.EXCITINGSODA_ACCESS_TOKEN);

Python

class ExcitingSoda:
    def __init__(self, bearer_token="", environment=Environment.DEFAULT) -> None:

from os import getenv
from excitingsoda import ExcitingSoda

sdk = ExcitingSoda(getenv("EXCITINGSODA_BEARER_TOKEN"))

Java

public class ExcitingSoda {
  public ExcitingSoda(String bearerToken) {}
  ...
}

import soda.exciting.ExcitingSoda;

ExcitingSoda client = new ExcitingSoda(System.getenv("EXCITINGSODA_BEARER_TOKEN"));

Refresh tokens

If your API supports refresh tokens, the liblab generated SDK can use these to ensure the user remains authenticated. In the config file, you can provide the endpoint from your API that is used to refresh the token, as well as the properties on the response object to use to read the new tokens.

For example, if this is the endpoint in your spec:

{
  "paths": {
    "/refreshToken": {
      "post": {
        "description": "Refresh a short lived access token",
        "operationId": "refreshToken",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RefreshTokenInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefreshTokenPair"
                }
              }
            },
            "description": "OK"
          }
        }
      }
    },
    ...
  }
}

You spec would also define the response object referred to by the #/components/schemas/RefreshTokenPair schema ref:

{
  "components": {
    "schemas": {
      "RefreshTokenPair": {
        "properties": {
          "accessToken": {
            "type": "string"
          },
          "refreshToken": {
            "type": "string"
          }
        },
        "type": "object"
      },
      ...
    }
  }
}

In this case, your config file would need to map the /refreshToken endpoint, along with the accessToken and refreshToken properties:

{
  "customizations": {
    "refreshToken": {
      "endpoint": "/refreshToken",
      "bearerKey": "accessToken",
      "refreshKey": "refreshToken"
    }
  }
}

These values need to match your spec, otherwise the SDK generation will fail.

Once this has been configured, the first time your API is called a refresh token will be requested. On subsequent calls, if the API returns a 401 (unauthorized) response, the SDK will automatically request a new access token using the refresh token, then retry the original request.