API keysAPI keys

You access the Pure API by means of an API key. API keys are created, updated, and deleted using the Pure backend application. An endpoint can only be accessed if the current API key is not locked, and is configured to allow access to the endpoint.

Adding the API endpoint /external-organizations/* to the list of allowed endpoints on an API key grants access to endpoints that work with external organizations, such as the /external-organizations  endpoint and all endpoints below /external-organizations/.

An API key is often referred to as 'a user API key', as it is associated with a specific Pure user. A Pure API request runs in the context of the user associated with the current API key. The privileges available to the user serve as a baseline; no operation triggered by invoking an endpoint can exceed it. If the user is not allowed to delete a Project, then an attempt at deleting it will fail even if the current API key allows access to an endpoint that deletes Projects. Similarly, an endpoint that returns Projects will only include a Project if the user has permission to read it.

An API key is also associated with an access definition. The access definition of an API key defines what data is accessible when endpoints are invoked, whereas the API key itself defines what endpoints can be invoked. Data access is restricted by applying content filters and field filters.

Content filters

✅ Available in 5.22.0 and later

An access definition contains a set of content filters. Content filtering configured on the access definition of the current API key is applied to content returned by endpoints. Some filters are always enabled to maintain the integrity of Pure, and some filters can be modified. For example, to allow access to content that is flagged as not being freely available, the option to 'Filter non-visible content' can be disabled, allowing clients to fetch content that would otherwise only be available on campus, or when using the Pure backend application.

Field filters

✅ Available in 5.22.0 and later

An access definition lists types that operate under the restrictions of API field filtering. API field filtering ensures that a field is only populated if the access definition of the current API key is configured to allow reading it. A field will not be populated if this is not the case. Likewise, a field value is only used for updates to Pure data if the access definition is configured to allow modifications using it. If this is not allowed, the field value specified on an incoming API model object will be silently ignored; it will have no effect on Pure content. It is always allowed to access "get-allowed" endpoint information, regardless of the field filter configuration, as this information is necessary to work with the API endpoint in question.
 

Metric collection filters

✅ Available in 5.27.1 and later

An access definition allows you to configure access to metric collections for types that supports metrics. Metric collection filtering configured on the access definition of the current API key affects what you get when using metric related operations. Access to metric collections is currently read-only, so you only need to decide what metric collections are available. You can either allow access to all current and future metric collections, or you can restrict access to only include select metric collections.