Scopes

Every token carries an explicit list of scopes. The check is default-deny: an endpoint requires a named scope, and a token without it gets 403. There is no implicit or wildcard grant, and no scope implies another.

Available scopes

Scope	Grants	Endpoints
certs:read	Read certificates and renewal requests	GET /v1/certificates, GET /v1/certificates/{id}, GET /v1/requests, GET /v1/requests/{id}
certs:renew	Open a renewal request for an existing certificate	POST /v1/certificates/{id}/renew

GET /v1/auth/validate needs only a valid token, no particular scope - use it as a health check for your credentials.

Choosing scopes

Give a token the smallest set that makes it work:

• Monitoring, dashboards, alerting - certs:read. This is most integrations.
• Automation that renews - certs:read and certs:renew.
• A read-only export for a report - certs:read, and consider a separate token you can revoke when the report is done.

What certs:renew can and cannot do

certs:renew opens a renewal in pending_approval. It cannot approve one. A token can therefore never, on its own, cause a certificate to be ordered from a CA or money to be spent - approval is a human action with the approver role in the Console.

This split matters when you are wiring NextPKI into an agent or an automation that you do not fully trust to be correct. The worst a compromised certs:renew token can do is create noise in the approval queue.

Organisation scoping

Tokens are tenant-scoped. Where an endpoint accepts org_id, it filters within that tenant. A token cannot be restricted to a single organisation in v1 - if you need that isolation today, use separate tenants.