Authentication

Creating a Personal Access Token

1. In Castrel, go to Settings → Access Tokens
2. Click Create Token
3. Fill in:
   • Token name: Choose a descriptive name, e.g., ci-script or local-dev (1–100 characters)
   • Expiration: Choose 30 days, 90 days, 1 year, or Never
4. Click confirm
5. Copy and save the token immediately — it won't be shown again after you close the dialog

Using a Personal Access Token

Pass the token as a Bearer token in the Authorization header:

curl -X POST "https://<your-instance>/personal/v1/knowledge/list" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"page_num": 1, "page_size": 20}'

Python Example

import requests

headers = {
    "Authorization": "Bearer <your-token>",
    "Content-Type": "application/json",
}

resp = requests.post(
    "https://<your-instance>/personal/v1/knowledge/list",
    headers=headers,
    json={"page_num": 1, "page_size": 20},
)
print(resp.json())

Upsert Knowledge

curl -X POST "https://<your-instance>/personal/v1/knowledge/upsert" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Common Ops Commands", "content": "## Disk Check\n```bash\ndf -h\n```"}'

Managing Tokens

Go to Settings → Access Tokens to view and manage your tokens.

Revoke

• Single revoke: Select Revoke from the token's action menu
• Batch revoke: Check multiple tokens, then click Revoke Selected

Revoked tokens stop working immediately. This cannot be undone.

Rotate

Rotation issues a new token and revokes the old one, keeping the same name and expiration window.

• Single rotate: Select Rotate from the token's action menu, then save the new token
• Batch rotate: Check multiple tokens, then click Rotate Selected

Security Tips

• Save your token to a password manager or environment variable — it's shown only once
• Never hardcode tokens in source code or commit them to version control
• Rotate long-lived tokens regularly and clean up unused ones
• Revoke immediately if you suspect a token has been exposed

FAQ

Can I view a token after creation? No — it's shown once. Rotate to get a new one if lost.

What happens when a token expires? API requests will return 401. Rotate to renew.

Can a token be used across workspaces? No — each token is scoped to the workspace where it was created.