Project tokens

A project token is a personal access token that lets the Athenode CLI, and your AI agent through it, act on one project. The web app names the page for them API Tokens, and the plan page counts them as "CLI tokens".

A token belongs to the member who created it and to one project. It acts with the role that member has in the project, so a token you create as an editor can do what an editor can do. Roles and permissions lists what a token can and cannot do.

Property	What it is
Name	A label you choose, such as the computer or the pipeline that uses the token.
Value	The secret itself. It starts with sdt_ and Athenode shows it once, when you create the token.
Expiry	30 days, 90 days, 180 days, 365 days or no expiry, chosen when you create the token.
Creator	The member who created the token. The token works while that member is in the project.

Create a project token

Create a token for each computer or pipeline that connects to the project, so that you can revoke one without disturbing the others. You need the editor or owner role. A viewer cannot create a project token, so an editor or the owner connects the Athenode CLI.

1. In the project, open Tokens.
2. Select New token.
3. Enter a Token name.
4. Choose the Expiry: 30 days, 90 days, 180 days, 365 days or No expiry. 90 days is preselected.
5. Select Create token.
6. In the Token created dialog, select Copy and store the token somewhere safe, such as a password manager. Athenode shows the token once.
7. Select Done.

The token appears under My tokens with its name, creation date and expiry.

The project's plan sets how many tokens each member can hold in the project: 1 on the Free plan, 10 on the Solo and Team plans and 20 on the Business plan. Expired tokens count until you revoke them. At the limit Athenode shows "Plan limit reached", and you revoke a token you do not use or the owner upgrades the plan. Plans and limits lists every limit.

Connect the Athenode CLI with the token

The Athenode CLI asks for the token the first time you run init in a local project directory. Run the first init in an interactive terminal, because the token is entered at a prompt.

1. In the root of your repository, run init:

   npx @athenode/cli init

2. At "Enter your athenode project token", paste the token and confirm with Enter.

3. Answer the remaining questions and confirm the plan that init shows.

The CLI stores the token in .athenode/config.json in that directory, and every later command there uses it. Your AI agent uses the same stored token through the Athenode MCP server that init sets up for each AI tool you selected. Install a setup describes the rest of init.

Each member connects with a token of their own, because a token acts as the member who created it, with that member's role.

Keep the token out of version control

.athenode/config.json holds your token, so it must stay out of your repository's history. When init stores the token, it adds .athenode/ to the repository's .gitignore for you. Leave that entry in place.

If a token reaches a commit, a log, a chat or a screenshot, treat it as public: revoke it, create a new one and replace it as described below.

Supply the token to the Athenode MCP server

The Athenode MCP server reads the stored token from .athenode/config.json. To give it a different token, such as a token of its own for a pipeline, set the ATHENODE_TOKEN environment variable where the AI tool starts the server:

export ATHENODE_TOKEN=<your-project-token>

ATHENODE_TOKEN takes precedence over the stored token for the Athenode MCP server only. Commands you run with the Athenode CLI use the token that init stored. Athenode MCP server describes how the server chooses the project it acts on.

Replace an expired or revoked token

An expired or revoked token stops working at once, and the Athenode CLI and your AI agent are refused until you store a new one.

1. Create a new token on the Tokens page.

2. In the root of your repository, run init in an interactive terminal:

   npx @athenode/cli init

3. The CLI reports that a project token is already stored and asks "Replace it?". Answer yes.

4. Paste the new token at "Enter your athenode project token".

5. Revoke the old token on the Tokens page if it is listed.

See and revoke tokens

Project tokens are listed, created and revoked in the web app. The Tokens page lists your tokens under My tokens with the columns Token, Created and Expiry. A token past its expiry date carries the Expired badge. The owner also sees Other members' tokens, each with the name of the member who created it.

Revoke a token when the computer that used it is retired, when the token may have been exposed, or when it has expired. You can revoke your own tokens, and the owner can revoke any token in the project.

On the Tokens page, select Revoke on the token's row and confirm in the Revoke token? dialog. The token leaves the list.

When a token stops working without being revoked

A token depends on its creator's membership of the project.

• When the creator is removed from the project or leaves it, the token stops working.
• When the creator's role changes to viewer, the token keeps working and can only read.
• When the creator confirms the deletion of their Athenode account, all of their tokens are deleted. Cancelling the account deletion does not bring them back.
• When the project is deleted, all of its tokens stop working.

Troubleshooting covers the errors the CLI reports for a missing, expired or revoked token.