Authentication
This topic explains how to create an API Client, furnish an API Key, set their permissions, and how to make requests on their behalf.
Overview
When creating a GraphQL endpoint, you may wish to restrict who has access to submit queries. With Brightspot’s GraphQL authentication features, you can control which clients have access to an endpoint, as well as what sites each client can retrieve content from.
Creating an API client
An API Client object represents an entity that has access to Brightspot’s GraphQL endpoints. The fields on the client object will determine what Sites it has access to, what endpoints it can query, and what API Keys it is associated with. To create an API Client, navigate to Admin > APIs in Brightspot and click New API Client on the left menu.
Endpoint permissions
Under the Endpoints section, you can enumerate what GraphQL endpoints this client can access. For endpoints that are configured to require API Key access, your client will also need to have an API Key associated with it in order to retrieve content from the endpoint.
Sites permissions
For detailed information about Sites Permissions, see Sites permissions.
Custom permissions
Developers may also create their own custom permissions by extending the ApiPermission class and implementing the hasPermission method. Note that in order for a client to access data from an endpoint, the request must satisfy all permissions associated with the client.After configuring your API Client’s permissions, click Save. Your client is now ready to make requests to your endpoint.
API keys
GraphQL endpoints can be configured to require an API Key for access. For external applications to access such a GraphQL endpoint, they must use a client’s API Key. This key is a unique identifier that verifies the authenticity of the entity making the request and applies the corresponding permissions.
Furnishing an API key
To generate an API Key for a client, click the name of the desired client from the left menu of the APIs Dashboard. Under the Keys section, click Add API Key and an API key for this client will be generated. Click the clipboard icon to copy the API key to your clipboard; it will not be available once you leave this page. Click Save once you have copied the key.
Making requests from a client
When making requests with an API Key, the X-API-Key header should be included on the request. The value of this header will be the key generated in the previous section. If the X-API-Key header is not included in the request, Brightspot will attempt to retrieve the apiKey query string parameter from the request URL. If no API Key can be resolved, the request will not execute and an error will be returned.