Access Keys

DYPAI 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

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

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 IDEs such as Cursor or Claude Desktop to your project.

• Used in MCP configuration
• Lets your AI assistant inspect and operate on project resources
• Found in Access → MCP Tokens

Which One Should I Use?

Using The SDK

User-facing app

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

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:

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

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

# .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:

1. Use jwt for user-facing endpoints and screens.
2. Use api_key only for backend-only automation or integrations.
3. 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
• SDK Auth — Implement login, signup, and recovery flows