Authentication
Choose credentials, grant the access you need, and authenticate a Prezly API request.
Every request in this guide uses a bearer token. Send it in the Authorization header over HTTPS:
Authorization: Bearer YOUR_TOKENThere are two kinds of credential. Choose one based on where your integration will run and whose access it should use.
Choose your credentials
| Credential | Use it for | How to get it |
|---|---|---|
| Personal API token | A local script or AI assistant acting with your own Prezly access. You choose its scopes and expiry. | Create one in Settings → API & integrations. |
| Integration API key | An ongoing integration or service. Its access is configured for the integration rather than a personal token's selected scopes and expiry. | Ask the Prezly Customer Success Team to help set up the key and its account/newsroom access. |
A token or key cannot bypass the access granted to it in Prezly. A personal token also cannot do more than the person who created it can do.
For the first API request, either credential works. A personal token with only the two read scopes below is enough.
Create a personal API token
- Open the Prezly account you want to connect and go to Settings → API & integrations.
- Under Personal API tokens, choose Add new token and give it a recognizable name, such as Local API walkthrough.
- Choose an expiry: 30 days, 90 days, or 1 year. The default is 30 days.
- Review Token permissions. The suggested selection is intended for MCP and includes permissions this walkthrough does not need. Keep
sites:readandstories:read, and remove the other optional permissions. - Choose Create token and copy it before closing the dialog. The full value is shown only once.
If you see an upgrade card instead of token controls, use View plans and upgrade or Talk to us to check availability for your account.
Permissions for this walkthrough
| Request | Required personal-token scope |
|---|---|
| List Newsrooms | sites:read |
| List Stories | stories:read |
| Get Story | stories:read |
Every personal token also includes account:read. Read access does not grant permission to create, publish, send, or delete anything.
Scopes restrict access; they do not grant new account permissions or access to another newsroom. Personal tokens are supported on an explicit set of endpoints, not every Prezly endpoint. They cannot be used with the Admin API.
Access for story authoring
The read-only walkthrough token cannot create or update content. Add stories:write for creating/updating stories, HTML conversion/import, and linking/unlinking translations. Read-before-update flows also need stories:read; newsroom lookup needs sites:read.
POST /stories/{story_id}/translate and translation suggestions are not on the personal-token allowlist. Use an integration API key for those endpoints; adding a write scope to a personal token does not enable them. Publishing and scheduling are separate operations with stories:publish for a personal token.
Integration-only workflows
Webhook management and privacy requests do not accept personal tokens. Use an integration API key with the relevant account access. Webhook management additionally requires webhook-view/manage permissions and is unavailable to newsroom integration credentials; arrange suitable account-level access with the Prezly Customer Success Team.
Snippets and sender management also require integration keys. Coverage supports personal tokens: reads need coverage:read, create/update need both coverage:write and contacts:write, and delete needs coverage:write.
Keep the credential on the server
Use an environment variable or your application's secret storage. Keep tokens out of source control, shared documents, screenshots, and browser JavaScript. A custom newsroom should make authenticated requests on its server rather than expose its credential to visitors.
Personal tokens must be sent in the Authorization header. Passing one in an access_token query parameter does not authenticate the request.
To replace a lost or expiring personal token, create a new one and update the client. Once the replacement works, revoke the old token under Personal API tokens. You can inspect a token's permissions and expiry there, but cannot reveal its full value again. If a token is exposed, revoke it and replace it.
Integration keys are managed separately. They do not expire automatically, but can be revoked or invalidated by regeneration.
Troubleshoot access
| Response | What to check |
|---|---|
401 | The bearer token is missing, invalid, expired, or revoked. Check the header and replace the credential if needed. |
403 with personal_api_token_missing_scope | Your personal token lacks a required scope. The response's required_scopes lists the scopes that must all be present. Create a replacement token with the necessary access. |
403 with personal_api_token_endpoint_not_allowed | That endpoint does not accept personal tokens. Check whether an integration key is needed. |
Other 403 responses | Check the account's permissions and the credential's access to the requested resource. |
404 when reading a story | Check the UUID and whether the credential can access that story's newsroom. A resource outside your access may not be visible. |
For broader failure handling and retry guidance, see Handling errors.
Next, make your first API request to verify your credentials and retrieve a story.