Authentication and authorization

Developer API keys, OAuth, regional endpoints, scopes and revocation.

Authentication

NudgeForMe REST accepts a developer key or Nudge OAuth access token in the Authorization: Bearer ... header. MCP accepts OAuth only.

Developer API keys

Create a named key in Settings → Developer API. Keys:

Begin with ndg_live_.
Are displayed once and stored as secure hashes.
Can expire after 1–365 days and be revoked immediately.
Support an optional single-workspace restriction.
Have a limit of 60 requests/minute per key.

Use these in secure server-side tools, including n8n. Never put a key into browser JavaScript or public Git history.

Step-by-step key creation

OAuth for MCP and third-party apps

OAuth supports authorization code with PKCE S256 and refresh-token rotation. Discovery endpoints:

/.well-known/oauth-authorization-server
/.well-known/oauth-protected-resource/mcp

The authorization server advertises /oauth/authorize, /oauth/token, /oauth/revoke, /oauth/register, and /oauth/jwks.json. Public dynamic client registration might be disabled; integrations can require a preregistered client.

Connect an MCP assistant

Permission scopes

Scope	Capabilities
`nudge.mailboxes.read`	Read workspaces and mailbox listings
`nudge.conversations.read`	Search sent conversations and read opportunities, details and status
`nudge.conversations.write`	Watch existing sent threads
`nudge.drafts.write`	Create follow-up drafts, not send
`nudge.followups.write`	Pause watched threads

Even a valid key cannot cross organization or workspace boundaries. External write endpoints reject auto-send mailboxes for safety.

Region separation

Global accounts use https://app.nudgeforme.com; EU accounts use https://europe.nudgeforme.com. OAuth keys, grants and customer data are separated by Firebase project and region.

Disconnect and revoke

Use Settings → Developer API to revoke keys and disconnect an OAuth application. Revocation invalidates existing authorization; reconnecting requires fresh approval.

Errors

The API returns JSON errors. Read Errors, limits and idempotency.

Was this page helpful?