Sites permissions
In a multisite Brightspot instance, you can restrict which sites an API client is allowed to access, and control which single site an individual GraphQL request resolves to for query filtering and mutation ownership. These are two independent controls: one governs what a client may reach at all, the other determines which site applies to a given request.
Restricting a client to specific sites
A client may be configured with one or more Sites permissions that determine which sites it can access. To modify a client's Sites permissions, navigate to the APIs Dashboard and select the client from the left menu, then, under Permissions, click Add Sites to add a Sites permission, add the sites you want the client to have access to, and click Save.
- If a client has no Sites permission, it has access to all sites.
- If a client has a single Sites permission listing one or more sites, it has access to the sites listed.
- If a client has multiple Sites permissions, it only has access to sites common to every one of those permissions.
Resolving the site for a request
Separately from client access, a GCA endpoint determines which site applies to a given request through a pluggable SiteSupplier, configured with siteSupplier(...) in schema settings or the Site field on editorial endpoints. The site a SiteSupplier resolves affects both queries and mutations—see Content mutations and the Schema Settings Reference for those effects. A SiteSupplier is optional: if none is configured, no site resolution happens and requests are not scoped to a site.
The GraphQL plugin ships five built-in SiteSupplier implementations:
| Supplier | Resolves the site by |
|---|---|
HeaderSiteSupplier | Reading a request header (X-Site by default). The value can be a site's URL or its ID. A value of *, or the configured default site URL, resolves to the Global site. Throws an error if the header is missing or its value does not match a site. |
ClientPermissionSiteSupplier | The current client's Sites permissions (see above). No Sites permission resolves to the Global site; access to exactly one site resolves to that site; access to more than one site throws an error, since nothing in the request indicates which one to use. |
RequestUrlSiteSupplier | The URL of the current request, matched against each site's configured URL. Requests to the default site URL resolve to the Global site. |
GlobalSiteSupplier | Always resolving to the Global site, regardless of client or request. |
ChainedSiteSupplier | Trying a list of other suppliers in order and returning the first one that resolves without error. |
GCA endpoints automatically allow the site-selection header for CORS requests, so browser clients using HeaderSiteSupplier need no additional CORS configuration for it. See Security.
For resolution logic the built-in suppliers do not cover—for example, deriving the site from a claim in a JWT—implement SiteSupplier directly and configure it the same way.