Authentication

BrainMaps API uses token-based authentication. There are two types of tokens:

1. Session Tokens (Web Application)
2. Personal Access Tokens (CLI/API Usage)

Session Tokens

Session tokens are automatically created when you log in through the web interface. These tokens:

• Are created on login
• Are automatically revoked on logout
• Cannot be manually created or revoked
• Are intended for web session management only

Personal Access Tokens

Personal Access Tokens (PATs) are long-lived tokens intended for CLI tools and API integrations. These tokens:

• Can be created manually through the API or web interface
• Persist until manually revoked
• Can have custom names for easy identification
• Are ideal for CLI tools and automated scripts

Creating a Personal Access Token

1. Log in to the BrainMaps platform
2. Go to your Account Settings
3. Navigate to the API Tokens section
4. Click “Create New Token”
5. Give your token a descriptive name
6. Copy the token immediately (it won’t be shown again)

Using Tokens with CLI

For automated or scripted usage of the CLI tool, you can authenticate using a token from the environment:

export BRAINMAPS_API_KEY=your_token_here
brainmaps --visual

Or directly when running the command:

BRAINMAPS_API_KEY=your_token_here brainmaps --visual

You can also store tokens in your .env file:

BRAINMAPS_API_KEY=your_token_here

The CLI will automatically:

• Verify the token on startup
• Skip the login screen if the token is valid
• Fall back to the login screen if the token is invalid or missing

Token Security

• Keep your tokens secure and never share them
• Store tokens in environment variables or secure configuration files
• Avoid committing tokens to version control
• Revoke tokens immediately if they’re compromised
• Consider rotating tokens periodically for security

Managing Tokens

You can manage your tokens through:

1. The web platform interface
2. The CLI tool: brainmaps token revoke <token_id>
3. The API endpoints (for programmatic management)

Token Expiration

• Session tokens expire after inactivity or logout
• Personal Access Tokens remain valid until manually revoked

API Authentication

All authenticated requests should include the token in the Authorization header:

curl http://localhost:8000/api/brains/ \
  -H "Authorization: Token YOUR_TOKEN"

Web Authentication Flow

1. User submits login credentials
2. Server validates credentials
3. Server generates session token
4. Token is stored in browser
5. Token is included in subsequent requests
6. Token is invalidated on logout