Authentication

Soxom supports four authentication methods, configured via OpenAPI security schemes or soxom.yaml.

Supported Methods

Method	OpenAPI Type	Description
Bearer Token	http: bearer	JWT or opaque tokens
API Key	apiKey	Header or query parameter
Basic Auth	http: basic	Username/password
OAuth 2.0	oauth2	Client credentials, authorization code

Configuration

soxom.yaml

authentication:
  # Primary auth method (from OpenAPI securitySchemes)
  default: bearer

  # Environment variable mappings
  env_vars:
    bearer:
      token: MY_API_TOKEN
    api_key:
      key: MY_API_KEY
    basic:
      username: MY_USERNAME
      password: MY_PASSWORD
    oauth2:
      client_id: MY_CLIENT_ID
      client_secret: MY_CLIENT_SECRET

  # OAuth 2.0 specific settings
  oauth2:
    token_url: https://api.example.com/oauth/token
    auto_refresh: true
    default_scopes:
      - read
      - write

OpenAPI Security Schemes

Define security schemes in your OpenAPI spec:

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

    apiKey:
      type: apiKey
      in: header
      name: X-API-Key

    basicAuth:
      type: http
      scheme: basic

    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.example.com/oauth/token
          scopes:
            read: Read access
            write: Write access

Bearer Token

The most common authentication method for modern APIs.

Configuration

authentication:
  default: bearer
  env_vars:
    bearer:
      token: ACME_API_TOKEN

Generated SDK

TypeScript

import { Client } from 'my-sdk';

// Direct token
const client = new Client({
  token: "your-api-token"
});

// From environment (automatic)
const client = new Client();
// Uses process.env.ACME_API_TOKEN

Python

from my_sdk import Client

# Direct token
client = Client(token="your-api-token")

# From environment (automatic)
client = Client()
# Uses os.environ["ACME_API_TOKEN"]

Go

import "github.com/example/my-sdk-go"

// Direct token
client := mysdk.NewClient(mysdk.WithToken("your-api-token"))

// From environment (automatic)
client := mysdk.NewClient()
// Uses os.Getenv("ACME_API_TOKEN")

API Key

For APIs using API key authentication in headers or query parameters.

Configuration

authentication:
  default: api_key
  env_vars:
    api_key:
      key: ACME_API_KEY

Generated SDK

TypeScript

const client = new Client({
  apiKey: "your-api-key"
});

Python

client = Client(api_key="your-api-key")

Basic Auth

For APIs using HTTP Basic authentication.

Configuration

authentication:
  default: basic
  env_vars:
    basic:
      username: ACME_USERNAME
      password: ACME_PASSWORD

Generated SDK

TypeScript

const client = new Client({
  username: "user",
  password: "pass"
});

Python

client = Client(
    username="user",
    password="pass"
)

OAuth 2.0

For APIs using OAuth 2.0 with client credentials or authorization code flow.

Plan requirement

OAuth 2.0 is available on Business and Enterprise plans only. Professional supports header-based authentication (bearer token, API key, basic auth) only — setting authentication.default: oauth2 or referencing an OAuth2 security scheme on a Professional plan rejects the build. See Usage limits.

Configuration

authentication:
  default: oauth2
  env_vars:
    oauth2:
      client_id: ACME_CLIENT_ID
      client_secret: ACME_CLIENT_SECRET
  oauth2:
    token_url: https://api.example.com/oauth/token
    auto_refresh: true
    default_scopes:
      - read
      - write

Generated SDK

TypeScript

// Client credentials flow
const client = new Client({
  clientId: "your-client-id",
  clientSecret: "your-client-secret"
});

// Token is automatically fetched and refreshed
const users = await client.users.list();

Python

# Client credentials flow
client = Client(
    client_id="your-client-id",
    client_secret="your-client-secret"
)

# Token is automatically fetched and refreshed
users = client.users.list()

Tip

When auto_refresh: true, the SDK automatically refreshes expired tokens before making requests.

Per-Operation Security

Override authentication for specific operations in your OpenAPI spec:

paths:
  /public/health:
    get:
      security: []  # No auth required
      responses:
        "200":
          description: Health status

  /admin/users:
    get:
      security:
        - oauth2: [admin:read]  # Requires admin scope
      responses:
        "200":
          description: Admin users list

Environment Variables

Soxom generates SDKs that automatically read from environment variables:

Auth Method	Default Env Var	Customizable
Bearer	{SDK_NAME}_API_TOKEN	Yes
API Key	{SDK_NAME}_API_KEY	Yes
Basic	{SDK_NAME}_USERNAME, {SDK_NAME}_PASSWORD	Yes
OAuth 2.0	{SDK_NAME}_CLIENT_ID, {SDK_NAME}_CLIENT_SECRET	Yes

Customize with env_vars in soxom.yaml.

Next Steps

• Pagination - Auto-pagination configuration
• Retries - Automatic retry handling