Skip to main content

Authentication

Most APIs use authentication (and sometimes authorization). Specmatic reads authentication requirements from your OpenAPI specification and sends the required headers or parameters during contract tests.

Specmatic supports these OpenAPI security schemes:

  • OAuth2
  • API Key
  • HTTP Bearer
  • HTTP Basic

How Specmatic chooses authentication for a request​

Specmatic reads the OpenAPI security requirement for each operation.

OpenAPI allows authentication to be defined at two levels:

  • Global level: top-level security (applies to all operations by default)
  • Operation level: security inside a specific endpoint/method (applies only to that operation)

Precedence rule​

If both are present, Specmatic gives preference to the operation-level security scheme.

This is useful when most endpoints use one auth scheme, but some endpoints use a different one.

Example: Global security with operation-level override​

openapi: 3.0.1

security:
  - BearerAuth: []   # Global default

paths:
  /products:
    get:
      security:
        - basicAuth: []   # Overrides global for GET /products
      responses:
        "200":
          description: OK

In this example:

  • Most endpoints use BearerAuth (global)
  • GET /products uses basicAuth (operation-level override)

Providing real auth credentials for contract tests​

When contract tests run against an environment that requires valid credentials, Specmatic needs real tokens or keys.

You can provide them in two ways:

  • Environment variables
  • specmatic.yaml security configuration (recommended; can read from environment variables)

Important: Security scheme names must match the OpenAPI spec​

The name you configure must match the security scheme name in components.securitySchemes.

For example, if your OpenAPI spec contains:

components:
  securitySchemes:
    oAuth2AuthCode:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/auth
          tokenUrl: https://example.com/token
          scopes: {}

Then the configured name must be oAuth2AuthCode.

You can configure auth values under the OpenAPI test configuration in specmatic.yaml.

specs:
  - spec:
      id: orderApiSpec
      securitySchemes:
        oAuth2AuthCode:
          type: oauth2
          token: ${OAUTH_TOKEN:OAUTH1234}
        basicAuth:
          type: basicAuth
          token: ${BASIC_AUTH_TOKEN:dXNlcjpwYXNzd29yZA==}
        apiKeyAuth:
          type: apiKey
          token: ${API_KEY:APIKEY1234}

This lets you:

  • Map each OpenAPI security scheme to a token/key
  • Read values from environment variables
  • Provide defaults for local testing

Environment variable values: what to provide​

Provide the raw credential value, not the full HTTP header.

Specmatic will construct the correct header format automatically based on the security scheme type.

Examples:

  • OAuth2 / Bearer: provide only the token (without Bearer )
  • Basic: provide only the Base64 credential (without Basic )
  • API Key: provide only the key value

Security scheme examples​

OAuth2​

OpenAPI example:

components:
  securitySchemes:
    oAuth2AuthCode:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://api.example.com/oauth/authorize
          tokenUrl: https://api.example.com/oauth/token
          scopes:
            users:read: Read user information

Configure:

  • Security scheme name: oAuth2AuthCode
  • Token value: abc123 (not Bearer abc123)

Specmatic sends:

  • Authorization: Bearer abc123

API Key​

OpenAPI example:

components:
  securitySchemes:
    ApiKeyAuthHeader:
      type: apiKey
      in: header
      name: X-API-KEY

Configure:

  • Security scheme name: ApiKeyAuthHeader
  • Token value: my-api-key-abc123

Specmatic sends:

  • X-API-KEY: my-api-key-abc123

HTTP Bearer​

OpenAPI example:

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

Configure:

  • Security scheme name: BearerAuth
  • Token value: abc123 (not Bearer abc123)

Specmatic sends:

  • Authorization: Bearer abc123

HTTP Basic​

OpenAPI example:

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic

Configure:

  • Security scheme name: BasicAuth
  • Token value: Base64 of username:password
  • Example: dXNlcjpwYXNzd29yZA== (user:password in Base64)

Specmatic sends:

  • Authorization: Basic dXNlcjpwYXNzd29yZA==

For contract tests, it is usually best to isolate your application from real auth providers (OAuth servers, DB-backed auth, identity services).

At this stage, the main objective is to validate that:

  • Your API advertises the correct auth requirements in the OpenAPI spec
  • Your application accepts the expected auth headers/parameters
  • Your service behavior matches the contract

You usually do not need to validate real token issuance/verification in contract tests. That is better covered in higher-level integration or end-to-end tests.

Use a test security setup that:

  • Checks header presence and format
  • Optionally creates a dummy authenticated principal/user
  • Avoids calling real auth dependencies

This is similar to using an in-memory database in tests instead of a production database.

Example: Different auth schemes per operation​

Specmatic supports different auth schemes for different endpoints in the same OpenAPI specification.

Example use case:

  • POST endpoints use OAuth2
  • GET endpoints use Basic Auth
  • DELETE endpoints use API Key

Specmatic reads the operation-level security entries and sends the appropriate auth header for each request.

Sample project:

Tips​

  • Security scheme names in specmatic.yaml must match names in components.securitySchemes.
  • If an operation defines security, it overrides global security.
  • Use environment variables in specmatic.yaml to switch credentials across local, CI, and test environments.
  • For contract tests, prefer mock/dummy auth unless your test specifically needs real auth.