# CORS (/docs/basic-concepts/cors)

A page in a browser can call the API directly, for example to build a cart with a limited token. For that to work, the page's origin must be on your account's list of allowed origins. This page shows how to add yours.

## Why it is needed [#why-it-is-needed]

Browsers block a page on one site from reading responses from another site unless that site agrees. This is called cross-origin resource sharing (CORS). The API agrees only for origins you list, so a page on someone else's site cannot use your shoppers' tokens.

A call from a page whose origin is not allowed is refused with `403`:

```json
{
  "error": {
    "type": "forbidden",
    "code": "invalid_origin",
    "message": "Invalid Origin. The request has been sent from an origin that is not approved for CORS requests. Allowed origins for cross-origin requests can be configured through account settings.",
    "reference": "c8kTbVL",
    "status": 403,
    "meta": null
  }
}
```

## Add your origins [#add-your-origins]

Add each site that calls the API from the browser under **Settings > Technical** in the dashboard, or with [Update technical settings](/api/settings/update-technical-settings):

```bash title="Request"
curl -X POST "https://api.comecero.com/api/v1/settings/technical" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "cors_allowed_origins": ["https://www.example.com", "https://shop.example.com"] }'
```

- An origin is the scheme and host only, such as `https://www.example.com`, with no path and no trailing slash. A port is not part of the match.
- Live mode needs `https`. Test mode also allows `http`.
- You can list up to 15 origins. The list replaces the one you had, so send all of them.
- Test and live settings are separate. An origin listed in either one is allowed.

## Allowed without setup [#allowed-without-setup]

- `localhost` and `127.0.0.1`, on any port, so you can build on your own machine.
- Your shop's own host names (`app_hosts` in the technical settings), such as `example.apps.comecero.com`.
- The Comecero dashboard.

Calls from a server or a tool like curl send no browser origin, so CORS does not apply to them.

## What the API allows [#what-the-api-allows]

For an allowed origin, the API answers the browser's preflight request and allows:

- Methods `GET`, `POST`, `PUT`, `PATCH`, `DELETE` and `OPTIONS`.
- Headers `Authorization`, `Content-Type`, `Accept`, `Origin`, `X-Requested-With` and `Cache-Control`.
- Reading the `X-Token-Expires-In-Seconds` response header, which tells the page how long its token has left.

Browsers keep the preflight answer for up to 24 hours, so most calls do not pay for an extra round trip.

<Callout type="warn">
CORS is for limited tokens and for trusted tokens in staff tools. Never send a secret token from a browser, even from an allowed origin. See [Authentication](/docs/basic-concepts/authentication).
</Callout>

Some accounts may not create payments or save payment methods from a browser on another origin. If a payment call from your page gets `403` with code `invalid_origin` while other calls work, contact support.

## Next steps [#next-steps]

<Cards>
  <Card title="Authentication" href="/docs/basic-concepts/authentication" />
  <Card title="Errors" href="/docs/basic-concepts/error-handling" />
</Cards>
