CORS is a browser security mechanism to allow Web sites to access data at (i.e. perform HTTP requests to) another origin (proto + domain + port).
In Single Page Applications this is often needed, if the API is running on different domain than the asset domain. For example, if users open
https://example.com and the Web App fetches from
It may also be needed in development setups, for example if the SPA is served by a hot-reloading asset server (such as WebPack or NextJS) on
localhost:3000 and FLAT is running on
CORS handling can be configured in the top-level section of
swagger.yaml with the extension object
swagger: "2.0"info:description: "…"version: "1.0.0"title: "My API"basePath: "/v1"x-flat-cors:allowed-origins:- "https://example.com"- "http://localhost:3000"allow-credentials: true
allowed-origins is a mandatory property that lists the origins that are allowed to use this API as an array of strings. Clients send their origin in the
Origin HTTP request header. If it matches one of the configured origins, it is reflected back to the client in the
If you only want to configure one origin, you can set
allowed-origins as a string:
The special origin
* allows all Websites to access the API.
The optional property
allow-credentials controls whether the browser is allowed to send
Authorization headers to the API. This is often necessary if the API wants to read access tokens from request headers. (Also see Working with JWT).
FLAT uses the OpenAPI definition to determine which HTTP methods ("operations") are allowed on which paths. This information is sent in response to the
OPTIONS pre-flight check in the
Access-Control-Allow-Methods: GET header.
Requests for URLs outside of the API
basePath are answered with
405 Method not allowed.
You can test the example
x-flat-cors configuration above with
curl to simulate pre-flight checks from different origins:
$ curl -i -X OPTIONS -H "Origin: http://localhost:3000" localhost:8080/v1/usersHTTP/1.1 200 OKDate: Tue, 06 Aug 2019 09:33:19 GMTServer: FLATAccess-Control-Allow-Origin: http://localhost:3000Access-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: GETContent-Length: 0
This location is not allowed:
$ curl -i -X OPTIONS -H "Origin: http://example.com:80" localhost:8080/v1/usersHTTP/1.1 200 OKDate: Tue, 06 Aug 2019 09:33:19 GMTServer: FLATAccess-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: GETContent-Length: 0
They look similar, but in the second request the
Access-Control-Allow-Origin header is missing.