API Access
Overview
Section titled “Overview”Fencer has two kinds of API credential. Both are tokens that start with fcr_, and both are sent as
Authorization: Bearer <token>:
- A service account belongs to an organization and has its own role. Use it for CI pipelines and other unattended automation. You manage service accounts under Settings > Service Accounts.
- A personal API key belongs to you and acts with your own access, in each organization that has approved it. You create keys in your user settings, and an organization admin approves them under Settings > Personal API keys.
To use the Fencer CLI interactively you do not need either: fencer login signs you in through your
browser (see Authenticate the Fencer CLI).
Prerequisites
Section titled “Prerequisites”| Task | Who can do it |
|---|---|
| See the Service Accounts and Personal API keys tabs | Roles with api_keys:read |
| Create a service account | Roles with api_keys:create |
| Revoke a service account | Roles with api_keys:delete |
| Approve, reject, or revoke a personal API key grant | Administrators |
| Create a personal API key | Any member, for organizations they belong to |
Of the built-in roles, only Administrator holds the api_keys abilities; you can add them to a
custom role. Creating or revoking a service account, creating or revoking a personal API key, and
deciding a grant all need you signed in to the web app: an API token cannot do them.
Service accounts
Section titled “Service accounts”Create a service account
Section titled “Create a service account”- Go to Settings > Service Accounts and click Create service account.
- Enter a Name (it must be unique among the organization’s active service accounts) and an optional Description.
- Pick a Role. The token acts with this role’s permissions. You can only pick a role whose permissions you hold yourself.
- Pick a Token expiry: 30 days, 90 days (the default), 365 days, or No expiration.
- Turn on Enable MCP access if the token should also work with the remote MCP endpoint. It is off by default.
- Click Create, then copy the token. It is shown only once.
Use the token with the CLI (fencer login --token or the FENCER_TOKEN environment variable) or
in your own API requests. A service account can only reach its own organization.
Review and revoke
Section titled “Review and revoke”Each service account shows its role, an Active or Revoked badge, an MCP badge when MCP access is on, the last four characters of its token, when it was last used, and who created it.
To revoke one, click Revoke and confirm. The account can no longer authenticate, and this cannot be undone. Service accounts cannot be edited: to change the role or rotate the token, create a new service account and revoke the old one.
Personal API keys
Section titled “Personal API keys”Create a key
Section titled “Create a key”- Click your avatar, select User settings, and open API keys.
- Click Create API key.
- Enter a Name and pick a Token expiry: 1 day, 7 days, 30 days, 90 days (the default), or 365 days.
- Under Organizations, select each organization the key should work in.
- Click Create, then copy the token. It is shown only once.
Each organization you select gets a Pending grant. The key does not work in that organization until an admin approves the grant. Once approved, the key acts with your own role there, so if your access changes, the key’s access changes with it. Use a service account when you need a narrower permission boundary, such as for CI.
A personal API key only works on organization-scoped requests (URLs that contain the organization
slug) and on the remote MCP endpoint. In the CLI, pass --org or set FENCER_ORG.
Manage grants and revoke
Section titled “Manage grants and revoke”On API keys, each key shows an Active, Expired, or Revoked badge, its expiry, when it was last used, and each organization grant with a Pending, Approved, Rejected, or Revoked badge. On an active key, click Manage grants to Add organization or Remove a grant. An added grant starts as Pending.
Click Revoke on an active key to revoke it. It can no longer authenticate, its pending and approved grants are revoked, and this cannot be undone.
Approve personal API keys for your organization
Section titled “Approve personal API keys for your organization”Go to Settings > Personal API keys. Grants that need a decision come first, marked Needs review, with the key’s name, its owner, and the last four characters of its token.
- Approve a pending grant to let the key act in this organization. The key owner cannot approve their own grant unless they are the organization’s only admin.
- Reject a pending grant, with an optional reason for the owner.
- Revoke an approved grant to remove the key’s access immediately, with an optional reason.
Fencer notifies admins when a grant needs review and tells the key owner about each decision, through the Personal API key approval requested and Personal API key grant decided notification triggers (see Notifications and Alerts).
Troubleshooting
Section titled “Troubleshooting”- “Cannot assign a role with permissions you do not hold yourself.” — pick a role at or below your own when you create a service account.
- “An active service account with this name already exists.” — pick another name, or revoke the old account first.
- “This operation requires an interactive session.” — creating or revoking credentials and deciding grants only work from the signed-in web app, not with an API token.
- “A different organization administrator must approve this grant.” — ask another admin to approve your key.
- A personal API key gets
404for an organization — its grant there is not approved yet, or was rejected or revoked.