Access Keys

HeroMate projects expose a small set of keys and tokens for different contexts. The most important rule is simple:

use jwt for user-facing app flows
use the project API Key only for server-to-server calls
treat service_role as internal/admin-only

Treat all keys like passwords. Never expose project API keys or service-role credentials in browser code, public repositories, or NEXT_PUBLIC_* variables.

The Three Access Credentials

API Key

Use the project API Key for endpoints configured with auth_mode: "api_key".

Sent via the X-API-KEY header
Accepted only on endpoints explicitly configured with auth_mode: "api_key"
Intended for server-side environments only
Best for backend jobs, workers, cron tasks, Route Handlers, and server-to-server integrations
Not for browser or mobile clients
Found under Settings → API Keys (route /api/keys)

The project API Key authenticates calls to your HeroMate endpoints. It is not the same as a third-party provider key (Stripe, OpenAI, Telegram…). Those go in Credentials, where they're stored typed and encrypted.

Service Role Key

This is an internal high-privilege credential.

Sent via Authorization: Bearer <key>
Grants internal service_role access
Reserved for trusted backend infrastructure, admin internals, migrations, or private tooling
Not part of normal app design
Never expose it outside a secure server context

MCP Token

Use the MCP token to connect AI clients such as Claude Code, Codex, Cursor, Windsurf, or Antigravity (and any other MCP-compatible tool) to your project.

Used in MCP configuration
Lets your AI assistant inspect and operate on project resources
Created on the org-level "Conectar IA" (MCP tokens) page at /{org}/mcp/tokens — the MCP card in the portal sidebar

Which One Should I Use?

Credential	Where to use it	Header	Typical use case
JWT session	Browser or mobile app	`Authorization: Bearer <user-token>`	Signed-in user flows
API Key	Server-side code only	`X-API-KEY`	Server-to-server endpoints
Service Role Key	Internal backend only	`Authorization: Bearer <key>`	Internal admin/system operations
MCP Token	AI client MCP config	MCP config	Connect Claude Code, Codex, Cursor, Windsurf, or Antigravity

Using The SDK

User-facing app

For browser or app authentication, initialize the SDK with only your project URL:

JavaScript

import { createClient } from '@dypai-ai/client-sdk'

const dypai = createClient(process.env.NEXT_PUBLIC_DYPAI_URL!)

This is the normal setup for:

login
signup
password recovery
calling jwt endpoints from the UI

Server-side app

If you need to call api_key endpoints from backend code:

JavaScript

import { createClient } from '@dypai-ai/client-sdk'

const dypaiServer = createClient(
  process.env.DYPAI_URL!,
  process.env.DYPAI_API_KEY
)

Store keys in server-only environment variables and never hardcode them in source files.

JavaScript

# .env
DYPAI_URL=https://your-project.dypai.app
DYPAI_API_KEY=your-project-api-key
DYPAI_SERVICE_KEY=your-internal-service-key

Recommended Usage Pattern

For most projects:

Use jwt for user-facing endpoints and screens.
Use api_key only for backend-only automation or integrations.
Keep service_role out of normal application architecture.

If you start with backend automation before user auth is ready, using api_key endpoints first is fine. When user-facing flows arrive, add jwt endpoints for those app actions.

Security Best Practices

Never expose the project API Key in browser code
Never put DYPAI_API_KEY in NEXT_PUBLIC_* or similar public env vars
Reserve the Service Role Key for internal backend processes only
Rotate keys if you suspect compromise
Add .env to .gitignore

Next Steps

Authentication — Understand user auth, roles, and endpoint protection
Endpoints — Build and expose your own API endpoints
Credentials — Store third-party provider keys (Stripe, OpenAI, Telegram…)
SDK Auth — Implement login, signup, and recovery flows

Access Keys

HeroMate projects expose a small set of keys and tokens for different contexts. The most important rule is simple:

use jwt for user-facing app flows
use the project API Key only for server-to-server calls
treat service_role as internal/admin-only

Treat all keys like passwords. Never expose project API keys or service-role credentials in browser code, public repositories, or NEXT_PUBLIC_* variables.

The Three Access Credentials

API Key

Use the project API Key for endpoints configured with auth_mode: "api_key".

Sent via the X-API-KEY header
Accepted only on endpoints explicitly configured with auth_mode: "api_key"
Intended for server-side environments only
Best for backend jobs, workers, cron tasks, Route Handlers, and server-to-server integrations
Not for browser or mobile clients
Found under Settings → API Keys (route /api/keys)

Service Role Key

This is an internal high-privilege credential.

Sent via Authorization: Bearer <key>
Grants internal service_role access
Reserved for trusted backend infrastructure, admin internals, migrations, or private tooling
Not part of normal app design
Never expose it outside a secure server context

MCP Token

Use the MCP token to connect AI clients such as Claude Code, Codex, Cursor, Windsurf, or Antigravity (and any other MCP-compatible tool) to your project.

Used in MCP configuration
Lets your AI assistant inspect and operate on project resources
Created on the org-level "Conectar IA" (MCP tokens) page at /{org}/mcp/tokens — the MCP card in the portal sidebar

Which One Should I Use?

Credential	Where to use it	Header	Typical use case
JWT session	Browser or mobile app	`Authorization: Bearer <user-token>`	Signed-in user flows
API Key	Server-side code only	`X-API-KEY`	Server-to-server endpoints
Service Role Key	Internal backend only	`Authorization: Bearer <key>`	Internal admin/system operations
MCP Token	AI client MCP config	MCP config	Connect Claude Code, Codex, Cursor, Windsurf, or Antigravity

Using The SDK

User-facing app

For browser or app authentication, initialize the SDK with only your project URL:

JavaScript

import { createClient } from '@dypai-ai/client-sdk'

const dypai = createClient(process.env.NEXT_PUBLIC_DYPAI_URL!)

This is the normal setup for:

login
signup
password recovery
calling jwt endpoints from the UI

Server-side app

If you need to call api_key endpoints from backend code:

JavaScript

import { createClient } from '@dypai-ai/client-sdk'

const dypaiServer = createClient(
  process.env.DYPAI_URL!,
  process.env.DYPAI_API_KEY
)

Store keys in server-only environment variables and never hardcode them in source files.

JavaScript

# .env
DYPAI_URL=https://your-project.dypai.app
DYPAI_API_KEY=your-project-api-key
DYPAI_SERVICE_KEY=your-internal-service-key

Recommended Usage Pattern

For most projects:

Use jwt for user-facing endpoints and screens.
Use api_key only for backend-only automation or integrations.
Keep service_role out of normal application architecture.

If you start with backend automation before user auth is ready, using api_key endpoints first is fine. When user-facing flows arrive, add jwt endpoints for those app actions.

Security Best Practices

Never expose the project API Key in browser code
Never put DYPAI_API_KEY in NEXT_PUBLIC_* or similar public env vars
Reserve the Service Role Key for internal backend processes only
Rotate keys if you suspect compromise
Add .env to .gitignore

Next Steps

Authentication — Understand user auth, roles, and endpoint protection
Endpoints — Build and expose your own API endpoints
Credentials — Store third-party provider keys (Stripe, OpenAI, Telegram…)
SDK Auth — Implement login, signup, and recovery flows