Give an application access to a content space
Register the website or app in API Consumers and issue its key, grant it one or more content spaces with a default channel, then turn its access off, remove it, or move it to a newer schema version.
- Applies to
- Headless CMS 1.0 and later
- Who can do this
- Administrator, Developer
- Permission
feature.hcms. access. create - Where
- Headless CMS › Delivery › API access
On this page
Before you start
- A Restricted space answers only applications granted here, each sending its own key. A Public space can be read by anyone without a grant, but a grant still gives an application a default channel and keeps it on the schema versions it reads.
- You need Create on API access (
feature.). The CMS Administrator role has it.hcms. access. create - The application must exist in Core. Applications and their keys are managed in Developer Tools › API Consumers, never in the Headless CMS, which doesn't store or show keys.
Steps
1. Register the application and issue its key (Core)
-
Open Developer Tools › API Consumers and add the application, for example
Company website. -
Select Issue key. Copy the key at once: it's shown only once.
-
Give the key to the application's developers, to keep in their server's settings.
Careful: Keys belong on servers, mobile apps and build tools. A web page running in a visitor's browser can't keep a key secret, and the delivery API doesn't accept one from a browser page. A website that reads content straight from the browser can read Public spaces only.
An application registered only by its website address, with no key, is treated as anonymous: it can read Public spaces, and its default channel and versions don't apply.
2. Grant it a content space
- Open Headless CMS › Delivery › API access.
- Select Grant access.
- In Application, search by name or identifier and choose the application. If it isn't listed, register it in API Consumers first, then come back: your choices are kept.
- Under Spaces, tick each space it should read. For each, choose a Default channel, or leave None: 'All channels' entries only.
- Under Versions, check the version of each schema it will read. They're preselected with what it receives today, so granting never changes its answers.
- Select Grant access.
You see, for example, 1 grant added. If the application had a grant to that space in the trash, it's restored with its default channel and versions instead.
If the application has no key yet, the drawer says This application has no key yet. On a Restricted space it's refused until a key is issued.
3. Check the grant
Each grant shows its application, space, Default channel, Key (from Core), Access, Versions and Last used.
| Key | Means |
|---|---|
| Key issued | It can read the space with its key. |
| No key: browser address only | On a Public space it reads as anyone does. |
| Waiting for a key | The space is Restricted and the application has no key yet. |
| Revoked | Its key was revoked in Core. |
| Off in Core / Removed in Core | The application was turned off or removed in API Consumers. It reads nothing as itself. |
Access reads Active, Off, or Active · no effect yet when the key or the application in Core stops it working.
Select Details to see What it can read now, the Versions it receives and the grant's History. Open in API explorer as application runs a request exactly as it would.
Change, turn off or remove a grant
- Edit: changes the Default channel only. It asks first and says what the application receives from its next request. To change the application or the space, remove the grant and grant again.
- Turn off: takes effect at once. On a Restricted space, its addresses answer "not found" to the application. On a Public space it can still read as anyone can, without its default channel. Undo is offered, and Turn on restores it later.
- Remove: the application stops reading the space at once, as if turned off, and the grant goes to the trash. Restore brings it back with its default channel and versions. Remove for good also deletes its version pins.
None of these touch the application or its key in Core. If the application is being taken out of service, switch it off or revoke its key in API Consumers too. A revoked or rotated key stops working within a minute. An application turned off in Core stops at once.
You can select several grants and turn them off, on, or remove them together.
Move an application to a newer schema version
When a schema publishes a new version, applications stay on the version they're pinned to. The grant's Versions show, for example, v2 available.
-
Ship the application's change first, so it can read the new shape.
-
Open the grant's Details, find the schema under Versions, and select Move to v2.
-
The dialog lists what changes between the versions, such as a field that is now sent under another name, and when the application last called the current version. Select Confirm.
From its next request without ?version=, it receives the new version. Undo is offered, and Move schema back returns it. See How schema changes and versions keep applications working.
What happens next
The application sends its key with each request, in the X-Api-Key header or as Authorization: Bearer. See Delivery API: addresses, parameters and responses. The space's page lists it under Who reads it.
Thanks. That helps us decide what to write next.
Thanks for telling us what was missing.
You already answered for this article today. Thanks.
We got a lot of answers from your network just now. Try again in a few minutes.
We couldn't send that. Check your connection and try again.
Links in this article
Printed from help.bsscn.com. The online article may have changed since.