Tokens

Areca uses several tokens. Each one grants one specific ability, so a leaked token exposes less than a password would. This page lists them, explains how they are stored, and gives the steps to take when one leaks.

OverviewCopy Anchor Link

Site and schema-write tokensCopy Anchor Link

Each site has two tokens for its site project. Both are created with the site and are shown once.

• Site token (ARECA_SITE_TOKEN). The site project uses it to read content types and the latest published content when it builds. It cannot change anything. Keep it in the environment of your deployment and in the build secrets, and in .env.local for local development.
• Schema-write token (ARECA_SCHEMA_TOKEN). The site project uses it only to push its content types to Areca. It is more powerful than the site token, so keep it out of production builds. Use it only in the environment where you define content types.

Each token works only for its own site. A token for one site cannot read or change another.

Storage and visibilityCopy Anchor Link

Areca generates each token as 32 random bytes and stores only a SHA-256 hash of it. This has two consequences:

• You cannot see a token again after it is shown. Areca cannot recover it either. If you lose a token, rotate it.
• The database holds no usable site tokens. A hash cannot be turned back into a token.

Rotate a tokenCopy Anchor Link

The old token stops working immediately. A build or pull that still uses it fails with an authorization error until you update it.

Preview tokensCopy Anchor Link

When an editor opens a preview of a draft, Areca creates a preview link for that one entry. The link includes a token that:

• names the site, the content type and the entry's slug,
• expires one hour after it was created,
• is signed with a secret that belongs to the site, so it cannot be changed without detection.

Preview tokens are not stored. Areca cannot revoke one early. If you need to stop a leaked preview link, wait for it to expire, which takes at most one hour. Preview links are for review, not for sharing with the public.

Setup tokenCopy Anchor Link

The setup token protects the first-run page at /setup, which creates the first agency admin. It is needed only while the instance has no users.

• If you set SETUP_TOKEN, use a value of at least 16 characters. That value is used.
• If you do not set it, Areca generates a random token the first time it checks for one while the instance has no users, and writes it to the server log. The token stays the same until the server restarts, and a restart before setup is complete creates a new one. Use the most recent value in the log.

Once the first admin exists, the setup token is no longer used. Complete setup promptly after installing, and do not expose /setup to the internet before then. See first run.

Metrics tokenCopy Anchor Link

The /api/metrics endpoint is off until you set METRICS_TOKEN to a value of at least 16 characters. Until then it returns 404. Once the token is set, scrapers send it as a bearer token, and requests with a missing or wrong token get a 401 response. The endpoint is limited per IP address; see rate limits.

Invitation linksCopy Anchor Link

Each invitation has a link that is valid for seven days and can be used once to join. Owners see pending invitations and can copy, resend or revoke them on the People page. Resending issues a new link with a new expiry, so the old link stops working. See people and invitations.

OAuth connectionsCopy Anchor Link

When you connect an AI app to a site on the Connect AI page, you sign in and approve on a consent screen. The app then receives tokens for that site only. It never sees your password or a secret that you could paste elsewhere.

• Scope. A connection belongs to one user, one app and one site. Its tokens name that site's connector URL as their resource, so a token for one site is refused at another. Approving a site does not cover other sites.
• Format. Access tokens start with areca_at_ and refresh tokens with areca_rt_. Both are opaque random strings, not signed data, so the server looks them up on each request. Secret scanners can recognise them by prefix.
• Storage. The server stores a SHA-256 hash of each access and refresh token, not the token. A hash cannot be turned back into a token. Each app is registered as a public client, which has no client secret and must use PKCE with S256.
• Lifetime. An access token lasts one hour, and the app renews it with its refresh token. A refresh token lasts 90 days from its last use, and each renewal issues a new one. A connection without successful MCP use for 90 days stops working and needs fresh consent. Token refresh alone does not extend this activity window. Offline connections continue working after your browser login session expires.
• Reuse. A client that loses a refresh response may retry it within 30 seconds and receives the same tokens. Reusing a refresh token after that window is treated as a leak: the server revokes that site’s connection and tokens. Other sites connected to the same app remain usable; reconnect the affected site with fresh consent. If an app then reports an authorization error, reconnect it from the Connect AI page.
• Permissions. A connection acts with your live role on the site, and checks it on every request. Going live and scheduling automatic publication need the approval checkbox on the consent screen, and only owners and agency admins can tick it.
• Proof-bound clients. DPoP clients must prove possession of their registered key on each request. Areca checks the proof against the token, method and public connector URL, and rejects reused proofs through a shared database replay store. A proof-bound token is refused as an ordinary Bearer token.
• Revocation. Disconnecting an app takes effect on its next request. It revokes the app's tokens for that site and removes the approval. Owners and agency admins can disconnect any app on the site, and editors can disconnect their own.

Each connection is recorded with who approved it and when, which is what the Connected apps list shows. See MCP endpoint and tools for the sign-in flow.

Personal AI keysCopy Anchor Link

A personal AI key lets one AI app work on one site as you. You create it on the Connect AI page. Its value starts with areca_mcp_, and it is sent in an Authorization: Bearer header to the site's MCP endpoint. Personal keys require Bearer authorization and do not support DPoP.

• Scope. A key belongs to one user and one site. It does not reach other sites or other clients, and it is not accepted by any site, preview or schema endpoint.
• Permissions. A key acts with your live role on that site, and checks it on every request. Going live needs a key created with Allow going live, and only owners and agency admins can create one.
• Storage. Areca generates 32 random bytes and stores only a SHA-256 hash. The key is shown once. If you lose it, revoke it and create a new one.
• Lifetime. You choose 30 days, 90 days, 1 year or never. The default is 90 days. An expired key stops working on its expiry date.
• Revocation. Revoking takes effect at once. Editors can revoke their own keys. Owners and agency admins can revoke any key on the site. Each key shows when it was last used, which helps you spot a key that is no longer in use.
• Limits. Each person can have 20 active keys per site. Requests made with a key are rate limited to 120 a minute per key, and to 600 a minute per client address when the address is known; see rate limits.

An agency admin can also create a personal agency key on Agency › Connect AI. It works on the agency connector for every client and site, and on no site's connector. Creating one needs a fresh authenticator code, its lifetime is chosen the same way, and it ends when the admin role ends.

A personal AI key is not a site token. It cannot be used to build a website, and a site token cannot be used to call the MCP endpoint.

If a token leaksCopy Anchor Link

Act on the token that leaked. The first step is always the same: stop the token from working.

If a token was in a Git commit, a log, or a shared chat, treat it as leaked. Rotating removes the risk of further use; it does not remove the token from history, so rotate even if you think nobody saw it.

RelatedCopy Anchor Link

• Secrets and encryption
• Two-factor authentication and step-up
• Connect AI for connected apps and personal AI keys.
• Site settings
• Preview explains how the site project renders previews.