Using Tokens with AI Agents

How to use Personal Access Tokens with AI coding assistants like Claude Code

Use Personal Access Tokens to let AI coding assistants like Claude Code read and write files in your CUEBES repositories. This enables powerful AI-assisted development workflows.

Overview

AI coding agents need programmatic access to your repositories. While Git operations use HTTPS authentication, AI agents can also use our REST API for more granular file operations. Both methods use Personal Access Tokens for authentication.

Creating a Token for AI Agents

  1. Go to Settings > Security
  2. Click "Create new token"
  3. Use a descriptive name like "Claude Code - Project Name"
  4. Select permissions:
    • Read - If the AI only needs to read code
    • Read & Write - If the AI should be able to create commits
  5. Optionally restrict to specific repositories
  6. Set an expiration (90 days recommended)
  7. Copy the token immediately - you won't see it again!
Tip: For maximum security, restrict tokens to only the repositories the AI needs access to.

Using with Claude Code

Setting Up the Token

Store your token as an environment variable:

# Add to your shell profile (~/.zshrc or ~/.bashrc)
export CUEBES_TOKEN="cubes_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Git Operations

Claude Code can clone and push using Git with your token:

# Clone a repository
git clone https://username:$CUEBES_TOKEN@cuebes.com/username/repo.git

# Or configure for an existing repo
git remote set-url origin https://username:$CUEBES_TOKEN@cuebes.com/username/repo.git

REST API Operations

Claude Code can also use the REST API for file operations:

# Read a file
curl "https://cueb.es/wp-json/cuebes/v1/codicles/{id}/editor/file?path=README.md" \
  -H "Authorization: Bearer $CUEBES_TOKEN"

# Create a file with commit
curl -X POST "https://cueb.es/wp-json/cuebes/v1/codicles/{id}/editor/file" \
  -H "Authorization: Bearer $CUEBES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "src/new-feature.swift",
    "content": "// New code here",
    "message": "Add new feature"
  }'

# Update a file
curl -X PATCH "https://cueb.es/wp-json/cuebes/v1/codicles/{id}/editor/file" \
  -H "Authorization: Bearer $CUEBES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "README.md",
    "content": "Updated content",
    "message": "Update README"
  }'

# Delete a file
curl -X DELETE "https://cueb.es/wp-json/cuebes/v1/codicles/{id}/editor/file" \
  -H "Authorization: Bearer $CUEBES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "old-file.txt",
    "message": "Remove old file"
  }'

# Browse file tree
curl "https://cueb.es/wp-json/cuebes/v1/codicles/{id}/editor/tree" \
  -H "Authorization: Bearer $CUEBES_TOKEN"
Note: Replace {id} with your repository's numeric ID. You can find this in your repository's URL or settings.

Available API Endpoints

Method Endpoint Description Scope
GET /codicles/{id}/editor/file Read file content read
POST /codicles/{id}/editor/file Create new file with commit write
PATCH /codicles/{id}/editor/file Update file with commit write
DELETE /codicles/{id}/editor/file Delete file with commit write
GET /codicles/{id}/editor/tree Browse file tree read

Repository API

Method Endpoint Description Scope
GET /codicles/{id}/commits List commits read
GET /codicles/{id}/branches List branches read
GET /codicles/{id}/tree/{ref} Get tree at ref read
GET /codicles/{id}/files List all files read

Authentication Headers

The API accepts tokens via two header formats:

# Preferred - Bearer token (standard OAuth2 format)
Authorization: Bearer cubes_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Alternative - Custom header
X-CUEBES-Token: cubes_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Security Best Practices

Token Security

  • Never commit tokens - Add .env to .gitignore
  • Use environment variables - Don't hardcode tokens in scripts
  • Restrict repository access - Only grant access to needed repos
  • Use minimum permissions - Use read-only if write isn't needed
  • Set expiration dates - Rotate tokens periodically

Monitor Activity

Regularly check your token's "last used" timestamp in Settings to spot unexpected activity.

Example Workflow

Here's a typical workflow when collaborating with Claude Code:

  1. Create a write-scoped token for your project repository
  2. Share the repository URL and ID with Claude Code
  3. Claude Code can then:
    • Read existing code to understand the project
    • Create new files with meaningful commit messages
    • Update existing files with improvements
    • Browse the repository structure
  4. Review the commits Claude Code creates in your repository

Troubleshooting

401 Unauthorized

Check that:

  • The token is correct and not expired
  • The Authorization header is properly formatted
  • The token has the required scope (read/write)

403 Forbidden

The token may not have access to this repository. Check:

  • Repository-scoped tokens are restricted to specific repos
  • The repository exists and you have permission

Related Articles

Using Personal Access Tokens Creating a Token Using Tokens in Xcode
Back to Help Center