Authentication

Overview

Magpipe supports two authentication methods. Both use Bearer token authentication via the Authorization header.

Method	Format	Expiration	Best For
API Key	`mgp_...`	Never (until revoked)	Server-side integrations, scripts, CI/CD
Session Token	`eyJ...` (JWT)	1 hour	Browser apps, short-lived sessions

We recommend API keys for most integrations. They don’t expire and are easier to manage.

API Keys (Recommended)

API keys are long-lived tokens that persist until you revoke them. They start with the mgp_ prefix.

Generating an API Key

Log in to magpipe.ai
Go to Settings → API
Click Generate New Key
Give the key a descriptive name (e.g., “Production Server”, “CI Pipeline”)
Copy the key immediately — it won’t be shown again

The full API key is only displayed once at creation time. Store it securely. If you lose it, you’ll need to generate a new one.

Using an API Key

curl -X POST "https://api.magpipe.ai/functions/v1/list-agents" \
  -H "Authorization: Bearer mgp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

const response = await fetch('https://api.magpipe.ai/functions/v1/list-agents', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.MAGPIPE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

Python

import requests
import os

response = requests.post(
    'https://api.magpipe.ai/functions/v1/list-agents',
    headers={
        'Authorization': f'Bearer {os.environ["MAGPIPE_API_KEY"]}',
        'Content-Type': 'application/json',
    },
    json={}
)

Key Properties

Prefix: All keys start with mgp_ followed by 40 hex characters
Display: In the dashboard, keys show as mgp_abc12345... (first 8 characters only)
Tracking: Each key tracks its last_used_at timestamp
Limit: Maximum 10 active keys per account

Revoking a Key

Go to Settings → API
Find the key you want to revoke
Click Revoke
Confirm the action

The key will immediately stop working. This cannot be undone.

Session Tokens

Session tokens are short-lived JWTs obtained by authenticating with email and password. They expire after 1 hour and can be refreshed.

Obtaining a Session Token

curl -X POST "https://api.magpipe.ai/auth/v1/token?grant_type=password" \
  -H "apikey: YOUR_ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "password": "your-password"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "..."
}

Using a Session Token

curl -X POST "https://api.magpipe.ai/functions/v1/list-agents" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{}'

Refreshing Session Tokens

Session tokens expire after 1 hour. Use the refresh token to get a new one:

curl -X POST "https://api.magpipe.ai/auth/v1/token?grant_type=refresh_token" \
  -H "apikey: YOUR_ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

Error Responses

If authentication fails, you’ll receive a 401 response:

{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized"
  }
}

Common causes:

Missing Authorization header
Invalid or expired token
Revoked API key

Security Best Practices

Use environment variables

Never hardcode tokens in source code. Use environment variables instead.

export MAGPIPE_API_KEY="mgp_your_key_here"

Use API keys for server-side code

API keys are ideal for backend services and scripts. Use session tokens only for browser-based apps where you authenticate with user credentials.

Name your keys descriptively

Use names like “Production Server” or “Staging CI” so you know which key is used where.

Rotate keys periodically

Generate new keys and revoke old ones regularly to limit exposure.

Monitor usage

Check your API key last_used_at timestamps in the dashboard to detect unauthorized usage.

API Reference

Agents

Custom Functions

Dynamic Variables

Memory

Calls

Call Whitelist

Skills

Batch Calls

Testing

Messages

Phone Numbers

Chat Widget

Knowledge Base

Voice

Models

Calendar

Contacts

Billing

Scheduled Actions

API Keys & Webhooks

Overview

API Keys (Recommended)

Generating an API Key

Using an API Key

Key Properties

Revoking a Key

Session Tokens

Obtaining a Session Token

Using a Session Token

Refreshing Session Tokens

Error Responses

Security Best Practices

​Overview

​API Keys (Recommended)

​Generating an API Key

​Using an API Key

​Key Properties

​Revoking a Key

​Session Tokens

​Obtaining a Session Token

​Using a Session Token

​Refreshing Session Tokens

​Error Responses

​Security Best Practices

Overview

API Keys (Recommended)

Generating an API Key

Using an API Key

Key Properties

Revoking a Key

Session Tokens

Obtaining a Session Token

Using a Session Token

Refreshing Session Tokens

Error Responses

Security Best Practices