Authentication Flows

Understanding VibeMap authentication methods.

VibeMap supports two primary methods of authentication depending on your use case. Choosing the right one is critical for security and performance.

1. Personal Access Tokens (Recommended)

Best for: Server-to-server integrations, CI/CD pipelines, and scripts.

Personal Access Tokens (PATs) are long-lived credentials that grant full access to your account's API. They are designed to be used in secure environments where you can safely store secrets.

Characteristics

• Prefix: Starts with vm_.

• Lifecycle: Valid until manually revoked.

• Permissions: Grants the permissions of the user who generated it.

• Usage: Included in the Authorization: Bearer <token> header.

Security Best Practices

• Never expose PATs in frontend code, client-side logs, or public repositories.

• Use environment variables to inject tokens into your application.

• Rotate tokens periodically if your security policy requires it.

---

2. Client-Side JWT (Supabase)

Best for: Building custom frontend applications or widgets that run in the user's browser.

If you are integrating VibeMap features into your own web application, you can use the user's active session token.

Characteristics

• Format: Standard JWT (JSON Web Token).

• Lifecycle: Short-lived; requires periodic refresh.

• Usage: Passed in the Authorization: Bearer <jwt_token> header.

How it Works

When a user logs into VibeMap, a JWT is generated. If your app shares an authentication provider (Supabase) or if you are proxying requests, you can use this token to authenticate.

---

Which one should I use?

Use Case	Recommended Method
Building a Jira/Linear sync service	Personal Access Token
Generating projects from a CLI tool	Personal Access Token
Adding a VibeMap "Save to Project" button in your app	Client-Side JWT
Automated nightly backups of project data	Personal Access Token

Implementation Example (Node.js)

const VIBEMAP_API_KEY = process.env.VIBEMAP_API_KEY;

async function fetchProjects() {
  const response = await fetch('https://vibemap.ai/api/crud/projects', {
    headers: {
      'Authorization': `Bearer ${VIBEMAP_API_KEY}`,
      'Content-Type': 'application/json'
    }
  });
  
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  
  return await response.json();
}