Skip to content
More from us
Appliku Deploy on your own servers SpeedPy The Django SaaS boilerplate

Integrations & Machine Auth

Overview

SpeedPy supports two machine-authentication methods for integrations:

  • OAuth2 (primary) — for MCP servers, ChatGPT/GPT Actions, automation platforms (n8n, Make.com), and CLIs
  • Personal Access Tokens (PATs) — for scripts, CI/CD pipelines, and local development tools

Which auth method to use

Use case Auth method Notes
Remote MCP server (Claude, Cursor) OAuth2 Device Code MCP spec mandates OAuth 2.1 for remote servers
ChatGPT / GPT Actions OAuth2 Authorization Code + PKCE Per-user access with consent screen
First-party CLI OAuth2 Device Code or PAT Device flow preferred; PAT for quick scripting
CI/CD pipelines PAT Non-interactive, short-lived scoped tokens
Shell scripts / cron jobs PAT Static bearer token via environment variable
n8n / Make.com / Zapier OAuth2 Authorization Code + PKCE These platforms support OAuth natively
Local/stdio MCP server PAT via env var Configured out-of-band in MCP client config
Server-to-server PAT Client Credentials grant can be added later

Connecting an MCP server

MCP (Model Context Protocol) servers let AI assistants like Claude and Cursor interact with your API. The MCP spec requires OAuth 2.1 for remote servers.

Step 1: Register the application

python manage.py create_oauth2_app "My MCP Server"

This creates a public OAuth2 application with the Device Code grant type and prints the client_id.

Step 2: Configure the MCP server

Point your MCP server at your SpeedPy instance with the client_id from step 1. See examples/mcp_server/speedpy_mcp.py for a ready-to-use implementation.

Step 3: Authorize

When a user first connects through the MCP client:

  1. The client calls POST /o/device-authorization/ with the client_id and requested scopes
  2. The user receives a user_code and opens /o/device/ in their browser
  3. The user enters the code and approves access
  4. The client polls POST /o/token/ until authorization completes

Using Personal Access Tokens

PATs are ideal for scripts and CI/CD where no browser is available.

Create a token

  1. Navigate to /accounts/tokens/
  2. Name the token and select scopes (e.g., read:profile, read:teams)
  3. Optionally set an expiry date
  4. Copy the token — it is shown only once

Use the token

curl -H "Authorization: Bearer spd_abc123..." https://your-app.com/api/v1/me/

Tokens use the spd_ prefix. Only a SHA-256 hash is stored — the raw token cannot be recovered.

ChatGPT / GPT Actions

To connect your SpeedPy API as a GPT Action:

  1. Register an OAuth2 application in Django admin with grant type Authorization Code
  2. Set the redirect URI to OpenAI's callback URL
  3. In the GPT builder, configure OAuth with:
  4. Authorization URL: https://your-app.com/o/authorize/
  5. Token URL: https://your-app.com/o/token/
  6. Client ID / Secret: from the registered application
  7. Scopes: e.g., read:profile read:teams

n8n / Make.com / Zapier

For automation platforms, PAT-based bearer auth is the fastest way to get started. For production multi-user integrations, use OAuth2 Authorization Code + PKCE.

See the dedicated Automation Platforms: n8n & Make.com guide for step-by-step setup instructions covering credential configuration, smoke tests, pagination handling, webhook triggers, and troubleshooting.

Dynamic Client Registration (RFC 7591)

The MCP spec recommends Dynamic Client Registration so MCP clients can self-register without manual admin setup. SpeedPy provides an optional registration endpoint.

Endpoint

POST /o/register/ (unauthenticated when DCR is enabled)

Request

{
  "client_name": "My MCP Client",
  "grant_types": ["urn:ietf:params:oauth:grant-type:device_code"],
  "scope": "read:profile read:teams",
  "token_endpoint_auth_method": "none"
}

Response (201 Created)

{
  "client_id": "abc123...",
  "client_name": "My MCP Client",
  "grant_types": ["urn:ietf:params:oauth:grant-type:device_code"],
  "scope": "read:profile read:teams",
  "token_endpoint_auth_method": "none",
  "client_id_issued_at": 1750000000
}

For confidential clients (Authorization Code grant), the response also includes a client_secret.

Configuration

# project/settings.py
DCR_ENABLED = env.bool("DCR_ENABLED", default=DEBUG)
  • Development: enabled by default — MCP clients can self-register
  • Production: disabled by default — register apps via Django admin or create_oauth2_app command

Warning

When DCR is enabled, any client can register an OAuth2 application. In production, either disable DCR or add authentication requirements (e.g., an initial access token).

Available scopes

Scope Description
read:profile Read the authenticated user's profile
write:profile Update the authenticated user's profile
read:teams Read teams and members
write:teams Create invitations and manage teams
read:products Read products
read:webhooks List and inspect webhook endpoints and deliveries
write:webhooks Create, update, and delete webhook endpoints
admin Administrative access (reserved)

Token creation requires selecting at least one scope. The PAT form and validation layer both read from the same scope registry defined in OAUTH2_PROVIDER["SCOPES"].

Registering custom scopes

Fork owners can add custom scopes for their own resources:

  1. Add entries to OAUTH2_PROVIDER["SCOPES"] in project/settings.py:

    OAUTH2_PROVIDER = {
    "SCOPES": {
        # ... built-in scopes ...
        "read:invoices": "Read invoices",
        "write:invoices": "Create and update invoices",
    },
    # ...
}

  2. Follow the naming convention read:<domain> / write:<domain>.

  3. The PAT creation form and scope validation automatically pick up new entries — no form changes needed.

  4. Set required_scopes on your API views:

    class InvoiceListView(APIView):
    permission_classes = [HasScope]
    required_scopes = ["read:invoices"]

  5. Add tests to verify that your custom scopes work with override_settings.

Starter examples

SpeedPy includes ready-to-use client examples in the examples/ directory:

Example Description
examples/cli/speedpy_cli.py CLI with PAT and device-flow auth
examples/mcp_server/speedpy_mcp.py MCP server exposing API tools for AI assistants
examples/mcp_server/generate_mcp_tools.py Generate MCP tools from the OpenAPI schema
examples/README.md Setup guide and extension instructions

Local MCP server quick start (PAT)

For local/stdio MCP usage (e.g., Claude Desktop, MCP Inspector), PAT auth is the simplest path:

  1. Create a PAT with scopes read:profile read:teams at /accounts/tokens/.
  2. Configure and run:
export SPEEDPY_API_URL=http://localhost:8000
export SPEEDPY_TOKEN=spd_your_token_here
python examples/mcp_server/speedpy_mcp.py
  1. Or add to Claude Desktop claude_desktop_config.json:
{
  "mcpServers": {
    "speedpy": {
      "command": "python",
      "args": ["/path/to/examples/mcp_server/speedpy_mcp.py"],
      "env": {
        "SPEEDPY_API_URL": "http://localhost:8000",
        "SPEEDPY_TOKEN": "spd_your_token_here"
      }
    }
  }
}

The server exposes get_current_user, list_teams, and list_team_members tools. For remote MCP servers, use OAuth2 Device Code flow instead (see above).