> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gunp.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Create and use personal access tokens in plamotrack

> Personal access tokens let scripts, the REST API, and MCP clients like Claude Desktop authenticate with plamotrack without using your browser session.

Personal access tokens are for anything that isn't a human in a browser — scripts, the REST API, Claude Desktop, Claude Code, and any other MCP client that sends HTTP headers. Your browser session is never used by these clients; they always need a token. Tokens are created in the app, shown once, and can be revoked at any time from the same place.

## Creating a token

<Steps>
  <Step title="Open Access tokens in Settings">
    Sign in to plamotrack and go to **Settings → Access tokens**.
  </Step>

  <Step title="Name the token">
    Under **Create a token**, give it a descriptive **Name** so you can identify it in the list later — for example, "Claude Desktop", "backup script", or "Claude Code".
  </Step>

  <Step title="Choose a permission level">
    Under **Access**, select the level the token needs:

    * **Read-only** — can list and view kits, orders, inventory, retailers, and settings. Enough for an agent that just looks things up.
    * **Read and write** — can also add and edit kits and orders, adjust stock, and import in merge or add-only mode.

    Choose the least permissive level that works for your use case. You can always revoke a token and create a new one with a different level.
  </Step>

  <Step title="Set an optional expiry">
    Under **Expires**, choose 30, 90 or 365 days, or leave it on **Never** for a token that does not expire. An expiry is automatic cleanup for short-lived uses.
  </Step>

  <Step title="Copy the token">
    Click **Create token**. Copy the token now — it is shown **once only** and looks like `ptk_<id>_<secret>`. Paste it directly into your MCP client config or store it in your password manager, then click **Done**. If you lose it, you'll need to revoke it and create a new one.
  </Step>
</Steps>

<Frame caption="Access tokens. The list shows each token by its prefix only; the full value appears once, when it is created.">
  <img className="block dark:hidden" src="https://mintcdn.com/plamotrack/cX9ROK0TihQzUKyA/images/screenshots/tokens-light.png?fit=max&auto=format&n=cX9ROK0TihQzUKyA&q=85&s=8a2b1b7ab3bb9aacf80c45b6819b15fb" alt="Settings → Access tokens: the Create a token form with Name, Access and Expires, and the token list below it showing one token by its prefix." width="2880" height="1800" data-path="images/screenshots/tokens-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/plamotrack/cX9ROK0TihQzUKyA/images/screenshots/tokens.png?fit=max&auto=format&n=cX9ROK0TihQzUKyA&q=85&s=0cd48cb8545b5447f3f8c5675108c398" alt="Settings → Access tokens: the Create a token form with Name, Access and Expires, and the token list below it showing one token by its prefix." width="2880" height="1800" data-path="images/screenshots/tokens.png" />
</Frame>

## Using a token

Pass the token as a Bearer token in the `Authorization` header on every request:

```http theme={null}
Authorization: Bearer ptk_your_token_here
```

This works on both the REST API (`/api/…`) and the MCP endpoint (`/mcp/`). Every MCP client and script should send this header — there is no cookie-based fallback.

<Warning>
  Never put the token in a URL (for example, `?token=…`). URLs are recorded in server logs — both nginx's and the API's. Always use the `Authorization` header.
</Warning>

## What a token can't do

Regardless of permission level, no token can:

* Change instance settings
* Run a replace-all import
* Manage (create, view, or revoke) other tokens

These actions require your owner browser session. This means a leaked token cannot lock you out or erase your collection.

## Revoking a token

Go to **Settings → Access tokens**, find the token, and click **Revoke**. Revocation is immediate — the token stops working the moment you click. The row stays in the list as an audit record. Minting, revoking, and any attempt to use a revoked token are all logged.

## Checking token usage

The token list shows when each token was last used. Check this periodically to spot tokens you no longer need, or to confirm that a client is connecting successfully.

<Tip>
  Create separate tokens for different uses — one for Claude Desktop, one for Claude Code, one for your backup script. That way you can revoke just one if it leaks or you retire a client, without affecting anything else.
</Tip>