This topic explains how to limit access to the data that clients can retrieve from your GraphQL endpoints to specific Sites.
Configuring sites permissions for a client
A client may be configured with Sites permissions that determine which sites the client has access to. To modify the Sites permissions for a client, navigate to the APIs Dashboard and select the desired client from the left menu.
Under Permissions, click Add Sites to add a Sites permission. Then, add the sites that you want your client to have access to and click Save.
A few notes here:
- If you don’t add a Sites permission, the client will have access to all sites.
- If you add one or more sites under the same Sites permission, the client will have access to the sites listed.
- If you add multiple Sites permissions to a client, the client will only have access to sites that are in each permission.
Making requests with multiple sites
When querying an API endpoint, the site should be specified in the request via the X-Site header or the site query string parameter in the request URL. The value of this field should be the URL or ID of the desired Site as displayed in Sites & Settings.
If both the X-Site header and site query string parameter are provided, the query string value will take precedence over the header value.
Including the Site parameter in your request is not mandatory, but if your client has access to more than one Site, the endpoint will be unable to determine the appropriate Site for your request and will return an error. The one caveat to this is if your client has global site permissions, in which case all content accessible to the global site can be retrieved. If your client only has access to one Site, then that available Site will be used by default, even if the Site parameter is not passed.
When using a CMA endpoint to create a piece of content, the Site that is passed (or automatically determined) will be assigned as that content’s owner site. Additionally, if you attempt to update a piece of content, but the Site passed does not match the Site that owns the content, an error will be returned and the content will not be updated. The exception to this is if the client making the request has global permissions and does not pass a Site in the request. In that case, the content’s owner site will be used as the site for the request.