Change Layer Docs
    Checking session...

    API Authentication

    Change Layer now exposes two API surfaces:

    • public reads under /v1/public/...
    • authenticated reads under /v1/...

    API access matters beyond embeds and frontends. It is also part of the broader direction for developer tooling, automation, and power-user workflows.

    Current route groups

    • GET /v1/public/teams/{teamSlug}/products/{productSlug}/changelog
    • GET /v1/public/teams/{teamSlug}/products/{productSlug}/changelog/versions/{versionId}
    • GET /v1/teams/{teamSlug}/products/{productSlug}/changelog
    • GET /v1/teams/{teamSlug}/products/{productSlug}/changelog/versions/{versionId}

    Two access modes

    • Public reads return published content intended for readers, embeds, or public pages.
    • Authenticated reads return team-scoped data for external clients using Bearer API keys.

    When auth is required

    NameTypeRequiredDescription
    Public changelog readsaccess modeYesNo signed-in user is required, but the team must be public and the requested product, changelog, and version data must already be published.
    Authenticated management routesaccess modeYesAuthenticated `/v1/...` reads require `Authorization: Bearer <apiKey>` and can return private-team, private-product, or draft changelog data when the key is allowed to access it.
    API keyscredentialNoUsed for authenticated programmatic read access and team-scoped integrations. Public published reads are available without a key, while paid plans currently unlock service API keys for authenticated `/v1` reads.

    What API keys are for

    API keys are intended for integrations that need authenticated access outside the normal browser session. They should be treated as team-scoped credentials and only exposed to authorized team members.

    That includes use cases like:

    • internal developer tools
    • scripts and CI workflows
    • product data syncs
    • authenticated CLI and workflow integrations

    Plan note

    Public published reads are available on all plans with heavy rate limits. Paid plans currently unlock service API keys for authenticated /v1 reads. Personal access tokens, authenticated write endpoints, and server-enforced read quotas are still future work.

    How authenticated /v1 reads work

    • The API expects Authorization: Bearer <apiKey>.
    • The API key must be active.
    • The key must belong to the teamSlug in the route.
    • FULL keys can read any product in that team.
    • SELECT keys can only read the products attached to that key.

    Plan gated feature

    API key creation for authenticated private-team and private-product reads is currently a paid feature. If the selected workspace is still on Hobby, use the upgrade link in the token manager below to unlock service API keys.

    Use the token manager below to list existing keys for the selected team, create a new one, and choose which active key should populate authenticated examples across the docs.

    Authenticated error semantics

    • 401 for missing, malformed, unknown, or disabled API keys.
    • 403 for a valid key targeting the wrong team or a disallowed product.
    • 404 for missing changelog or version resources.

    What is public today

    • Public routes use the /v1/public/... prefix.
    • Public routes return published content only.
    • Public routes return 404 for private teams and unpublished content so the API does not leak private objects.
    • Public routes are heavily rate limited.

    What authenticated routes unlock

    • Private teams
    • Draft or locked products
    • Draft changelogs
    • Draft versions
    • Authenticated reads only today. The current /v1/... surface does not expose write routes yet.

    Deployment caveat

    Password-protected deployments

    In deployments with PASSWORD_PROTECTION=true, middleware applies site-wide Basic auth to /api routes before the REST handlers run. That means even the public /v1/public/... endpoints require Basic auth in those environments.

    Security note

    Follow-up hardening

    API keys are still stored in plaintext in the current model so this first authenticated /v1 slice can ship quickly. The next hardening pass should move them to hash-at-rest or encrypted-at-rest before the authenticated API surface expands further.

    What still requires future work

    • Authenticated write endpoints
    • Scope-based API permissions beyond team and product restriction
    • Personal access tokens for CLI and user-scoped automation
    • Server-enforced plan quotas and rate limits for authenticated /v1 reads

    Related guides