Skip to main content
A service account is a Forest identity for software, a script, an AI agent or an integration that calls your Forest back-end without signing in as a person. It has a Role and Teams like any user, sees only what its Role allows, and authenticates with application tokens you generate for it. Only Admins can manage service accounts.

​
Accessing service accounts

  1. Click your project logo in the top-left corner
  2. Select Project Settings
  3. Navigate to the Service accounts tab
Service accounts tab listing an account with its Role, Team, application tokens and creation date

The Service accounts tab in Project Settings

The table shows each account’s Role, Teams, number of application tokens and creation date. The Service accounts tab replaces the former API Keys tab, and old /settings/api-keys links open it.

​
How a service account differs from a user

  • It never signs in. Forest refuses a service account on every sign-in method, password, SSO or Google, so it cannot open the Forest UI. It reaches your data only through an application token.
  • Its permission level is always User. It cannot be made an Admin, so it cannot change your project settings. What it can do with your data depends on its Role.
  • It is not counted with your users. Service accounts do not appear in your project’s user count.
  • Its actions are attributed to it. What it does through the Gateway is recorded in your activity logs as the service account’s activity.

​
Creating a service account

  1. Click New service account
  2. Fill in:
    • Name - What the account is for, for example Refund bot or Support assistant
    • Team(s) - One or more teams. A token only works on a team the account belongs to
    • Role - The Role that decides which collections, fields and actions the account can use
  3. Click Create service account
Create a service account form with Name, Team(s) and Role fields

Create a service account with a name, one or more teams and a Role

The account’s details page opens. You can change its Role and Teams there at any time, but not its name.
Your back-end applies a Role change at its next permissions refresh, as it does for any user. A Node.js agent refreshes right away through the Forest event stream when instantCacheRefresh is on, the default, and after permissionsCacheDurationInSeconds when it is off, see Permissions and caching. The permission hints the Gateway serves at GET /api/agent/v1/permissions can lag for up to 15 minutes.

​
Generating an application token

An application token lets an application authenticate as the service account. Each token is tied to one environment and one team, so you can give each application its own token, or hold two while you rotate one.
These are not the application tokens of your account settings. Those are personal, act as you, and serve the Forest CLI and the Public API.
  1. On the service account’s page, click Generate application token
  2. Fill in:
    • Name - Where the token is used, for example n8n production
    • Environment - The token only works on this environment
    • Team - The team whose layout the token uses on this environment. The field only appears when several of the account’s teams can reach that environment
  3. Click Generate application token
Generate an application token form with Name and Environment fields

Generate an application token for one environment

The token’s page opens with its secret, a value starting with fgw_. It is copied to your clipboard when your browser allows it, and a Copy button sits next to it.
Application token details page with the blurred secret, its Copy button and the only-displayed-once warning

The secret is shown once, on the token page

The secret is displayed only once. Forest stores a hash of it, not the value, so leaving or reloading the page loses it for good. Store it in your secret manager before you leave. If you lose it, generate a new token and revoke the old one.
The form has no expiration setting: a token generated here shows Never in its Expiration column and stays valid until you revoke it, or until one of the conditions in When a token stops working applies. Generate application token is blocked in two cases:
  • The account has no Role. Assign one on its page first.
  • No environment is available. The account’s Role must enable at least one environment its Teams can reach. Enable an environment on the Role, or add a Team.

​
Using an application token

Application tokens authenticate on the Forest Gateway, against the environment and team they were generated for:
  • API service - Send the token in the X-Forest-Gateway-Key header:
    The header needs @forestadmin/agent 1.110.1 or later embedded, or @forestadmin/gateway 1.0.2 or later standalone. Earlier versions read the token from X-Forest-Bff-Key, which stays accepted as an alias. A token reaches the read and action routes, list, count, relations, action form and execute, context and permissions. ai/query requires an OAuth sign-in and answers 403 oauth_required.
  • MCP service - Send the token as a bearer, Authorization: Bearer fgw_.... The account gets the MCP tools, writes included, within what its Role allows.
Don’t send a bearer and a token, or two different tokens, on the same API request: the Gateway answers 400 ambiguous_credentials. See Authentication.
The Gateway’s allowedOAuthClients restricts OAuth client applications. It does not apply to application tokens, which authenticate a service account directly. See Restricting which OAuth clients can connect.

​
When a token stops working

Each time the Gateway checks a token, the token’s service account must:
  • have a Role,
  • still be a member of the token’s team,
  • have a Role that enables the token’s environment, unless roles are disabled on your project.
Otherwise the API service refuses the token with 403 forest_identity_not_allowed, and a revoked, unknown or malformed token gets 401 invalid_api_key. The MCP service answers with the matching OAuth errors, insufficient_scope and invalid_token. These checks are cached. Removing the account from the team, or disabling the environment on its Role, takes effect within a few minutes, like a revocation. The Gateway also remembers a refusal for about ten seconds. After you fix the cause, for example by enabling the environment on the account’s Role, retry after that delay.

​
Revoking an application token

  1. Open the service account, then the token under Application tokens
  2. In the Danger Zone, click Revoke application token
  3. Type the token’s name to confirm, then click Revoke application token
Revoke application token dialog asking to type the token name

Type the token name to confirm the revocation

Revoking cannot be undone. The service account and its other tokens keep working.
Revocation is not instant. Forest refuses the token from the moment you revoke it, but the Gateway caches a resolved token and the access it already issued, so calls can keep succeeding for a few minutes. Revoke a leaked token first, then rotate whatever it gave access to.
Some changes revoke tokens for you:
  • Removing the account from a team revokes its tokens on that team.
  • Deleting a team revokes every service account token on that team.
  • Deleting the service account revokes all its tokens.

​
Deleting a service account

  1. Open the service account’s details page
  2. In the Danger Zone, click Delete service account
  3. Type the account’s name to confirm, then click Delete service account
Deleting a service account revokes every application token it holds, and the applications using them stop working. Inbox automations set to run as the account are detached from it.

​
What’s next

Forest Gateway

Mount the Gateway that application tokens authenticate against.

Roles & permissions

Decide what a service account can see and do.