Ask a Question

Can securitySchemes be defined in a domain?


Can securitySchemes be defined in a domain?

I'm trying to use domain specs (OAS3) to define standard, reusable components that can be used in multiple APIs. I'm getting errors when I try to use a $ref: to add a securityScheme that was defined in a domain to the security property of an API. It works fine if the components.securitySchemes are defined directly within the API spec itself. I've done some searching and I can't find any documentation or examples showing how to make this work, but I also haven't found anyplace where it says this can or can't be done. To illustrate:


In my domain spec (Example-Domain/1.0.2) I have the following:

      type: http
      scheme: bearer
      bearerFormat: JWT

In my API spec I have this:

  - $ref: ''


The following error are returned for the line containing the $ref:

  1. should be an array
  2. Security requirements must match a security definition

If I put the same security scheme definition into the API spec itself and modify the security section as follows, it works fine.

  - bearerToken: []


Am I doing something wrong?



SmartBear Alumni (Retired)

Hi @MOverholt-AFI,


Currently, domains cannot contain security schemes:

Note: The OpenAPI 3.0 components section can contain securitySchemes, however, domains cannot contain them.

There's a feature request in our internal tracker to support this in the future, and I've added your vote to it.

Helen Kosova
SmartBear Documentation Team Lead
Did my reply answer your question? Give Kudos or Accept it as a Solution to help others. ⬇️⬇️⬇️
Showing results for 
Search instead for 
Did you mean: