Overrides

Real-world API specs aren’t perfect. Some declare authentication incorrectly, others have vague descriptions, and some have outdated server URLs. Overrides let you fix these issues without modifying the original spec.

Why Overrides Exist

The most common problem: 60% of real-world APIs declare authentication as header parameters instead of proper security schemes.

# What many specs do (problematic):
parameters:
  - name: Authorization
    in: header
    required: true

# What they should do:
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

When authentication is declared as a parameter, Toolcog can’t:

• Automatically handle credential storage
• Trigger the OAuth flow when needed
• Manage token refresh

Overrides fix this by converting parameter-based auth to proper security schemes.

Override Scoping

Overrides can apply at different levels:

Global Overrides

Apply to all operations in a catalog:

Scope: All operations
Override: Normalize Authorization headers to bearer tokens

Per-API Overrides

Apply to operations from a specific API:

Scope: All Stripe operations
Override: Use custom server URL

Per-Operation Overrides

Apply to specific operations:

Scope: github/repos.create
Override: Mark as deprecated

More specific scopes override broader ones.

Authentication Overrides

OAuth Override

Define OAuth2 authentication for an API:

type: oauth
schemeName: oauth2
grantType: authorization_code
authorizationUrl: https://github.com/login/oauth/authorize
tokenUrl: https://github.com/login/oauth/access_token
scopes:
  - repo
  - user
realm: toolcog/github

Bearer Override

Define bearer token authentication:

type: bearer
schemeName: bearerAuth
normalizeHeaders: true # Convert Authorization header param

API Key Override

Define API key authentication:

type: apikey
schemeName: apiKey
in: header
name: X-API-Key
normalizeHeaders: true

Basic Auth Override

Define HTTP Basic authentication:

type: basic
schemeName: basicAuth
normalizeHeaders: true

Content Overrides

Description Override

Replace an operation’s description:

type: description
value: |
  Creates a new customer in your Stripe account.

  The customer object represents a customer of your business.
  Use this to store contact information and payment methods.

Summary Override

Replace an operation’s summary (the short one-liner):

type: summary
value: Create a new customer

Structure Overrides

Server Override

Change the base URL for API calls:

type: server
url: https://api.example.com/v2

Useful for:

• Pointing to staging environments
• Using custom domains
• Switching API versions

Deprecated Override

Mark an operation as deprecated:

type: deprecated
value: true

Strip Override

Remove examples or extensions from specs:

type: strip
examples: true # Remove example values
extensions: true # Remove x-* extensions

Useful for reducing spec size or removing sensitive examples.

Parameter Override

Modify a parameter’s properties:

type: parameter
name: customer_id
description: The unique identifier for the customer
required: true

Override Strategies

Control when overrides apply:

always

Override regardless of what the spec says:

strategy: always

when-missing

Override only if the spec doesn’t define it:

strategy: when-missing

when-undeclared

Override only if no security scheme is declared:

strategy: when-undeclared

Automatic Normalization

Toolcog automatically applies some normalizations:

Authorization Header Detection

If a spec has:

parameters:
  - name: Authorization
    in: header

Toolcog automatically:

1. Detects this is likely authentication
2. Converts to a proper bearer security scheme
3. Removes the duplicate parameter

You can disable this with explicit overrides if needed.

Applying Overrides

In the Dashboard

1. Navigate to your catalog
2. Go to Overrides
3. Click Add Override
4. Select scope (API, operation, or global)
5. Configure the override type
6. Save

Override Order

When multiple overrides could apply:

1. Operation-specific overrides apply first
2. API-specific overrides apply second
3. Global overrides apply last

Earlier overrides take precedence.

Examples

Fix an API with Header-Based Auth

scope: myapi/*
type: bearer
schemeName: bearerAuth
normalizeHeaders: true
realm: myorg/myapi-realm

Add OAuth to GitHub Operations

scope: github/*
type: oauth
schemeName: github_oauth
grantType: authorization_code
authorizationUrl: https://github.com/login/oauth/authorize
tokenUrl: https://github.com/login/oauth/access_token
realm: toolcog/github

Use a Staging Server

scope: myapi/*
type: server
url: https://staging-api.example.com

Improve a Vague Description

scope: stripe/customers.create
type: description
value: |
  Creates a new customer in Stripe with the provided details.
  Returns the created customer object including the generated ID.

Next Steps

• Variables — Dynamic catalog configuration
• Override Types Reference — Complete override reference