Server and Authentication Extensions

These extensions describe where your API runs and how clients authenticate with it.

Define environments and serversCopy Anchor Link

x-server-configuration in the Info Object defines the environments your API runs in, the servers in each environment, and the parameters used in server URLs.

info:
  title: Payments API
  version: 1.0.0
  x-server-configuration:
    default-environment: production
    default-server: api
    environments:
      - name: production
        description: Live environment
        servers:
          - name: api
            url: https://{region}.example.com
          - name: auth
            url: https://auth.example.com
      - name: sandbox
        servers:
          - name: api
            url: https://sandbox.example.com
          - name: auth
            url: https://auth.sandbox.example.com
    parameters:
      - name: region
        description: Region the API is served from
        schema:
          type: string
          enum: [us, eu]
          default: us

An Environment object has a name, an optional description, and servers, an array of Server objects. Every environment must define the same set of server names.

A Server object has a name and a url. In OpenAPI 3.x, a server can also have its own parameters (Parameter Objects) or variables (Server Variable Objects) for the placeholders in its URL.

Give each URL parameter a default value. If a parameter has no default, APIMatic uses its example instead.

Set the server for an endpointCopy Anchor Link

To send an endpoint's requests to a server other than the default server, set x-server-name in its Operation Object to the name of a server in your server configuration.

paths:
  /token:
    post:
      operationId: createToken
      x-server-name: auth

Add headers to every requestCopy Anchor Link

x-additional-headers in a Security Scheme Object lists headers that are sent with every request, on top of the headers that authentication or parameters add.

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      x-additional-headers:
        - name: api-version
          description: Version of the API to use
          schema:
            default: "2024-01-01"

Each header has a name, an optional description, and a default value. In OpenAPI 3.x, put the default value in schema.default; in Swagger 2.0, put it in default.

Rename Basic authentication credentialsCopy Anchor Link

By default, Basic authentication takes a username and a password. To use different names, set these extensions in the Security Scheme Object:

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      x-rename-username-as: accountId
      x-rename-password-as: apiSecret

OAuth 2.0 extensionsCopy Anchor Link

In OpenAPI 3.x, add these extensions to an OAuth Flow Object inside flows. In Swagger 2.0, add them to the OAuth 2.0 Security Scheme Object.

x-revoke-token takes these properties. Their names are case-sensitive.

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.example.com/oauth/token
          scopes:
            payments:read: Read payments
            payments:write: Create payments
          x-oauth2-clientid-example: my-client-id
          x-oauth2-clientsecret-example: my-client-secret
          x-oauth2-credentials-placement: body
          x-default-scopes:
            - payments:read
          x-revoke-token:
            Url: https://auth.example.com/oauth/revoke
            TokenType: Access
          x-additional-oauth-fields:
            account_id:
              type: string

Name security optionsCopy Anchor Link

Each item in a security array is a security option: a set of schemes that a client can use to authenticate. x-security-options-meta, next to security at the root or in an Operation Object, gives each option a name and a description.

security:
  - {}
  - apiKey: []
x-security-options-meta:
  - name: No authentication
    description: Limited access without credentials.
  - name: API key
    description: Full access with the API key from your account settings.

The extension must have exactly one item per security option, in the same order. If the counts don't match, APIMatic ignores the extension and reports a warning.

APIMatic imports security options only when the ImportMultipleAuthentication import setting is true, which is the default. See Import and Export Settings.