# CORS - Cross-Origin Resource Sharing

[CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/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 `https://api.example.com`.

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 `localhost:8080`.

## Configuration

CORS handling can be configured in the top-level section of `swagger.yaml` with the extension object `x-flat-cors`:

```yaml
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 `Access-Control-Allowed-Origin` header.

If you only want to configure one origin, you can set `allowed-origins` as a string:

```yaml
x-flat-cors:
  allowed-origins: "https://example.com"
```

The special origin `*` allows all Websites to access the API.

The optional property `allow-credentials` controls whether the browser is allowed to send `Cookies` or `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](https://sevenval.gitbook.io/flat/cookbook/jwt)).

## Swagger Integration

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`.

## Example

You can test the example `x-flat-cors` configuration above with `curl` to simulate pre-flight checks from different origins:

```bash
$ curl -i -X OPTIONS -H "Origin: http://localhost:3000" localhost:8080/v1/users
HTTP/1.1 200 OK
Date: Tue, 06 Aug 2019 09:33:19 GMT
Server: FLAT
Access-Control-Allow-Origin: http://localhost:3000
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET
Content-Length: 0
```

This location is not allowed:

```bash
$ curl -i -X OPTIONS -H "Origin: http://example.com:80" localhost:8080/v1/users
HTTP/1.1 200 OK
Date: Tue, 06 Aug 2019 09:33:19 GMT
Server: FLAT
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET
Content-Length: 0
```

They look similar, but in the second request the `Access-Control-Allow-Origin` header is missing.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://sevenval.gitbook.io/flat/reference/openapi-1/cors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.