Skip to main content

Authentication

Promptsy uses OAuth 2.1 to securely authenticate MCP connections. This ensures your prompts stay private and you control which AI assistants can access your vault.

How It Works​

┌──────────────┐    1. Request auth    ┌──────────────┐
│ AI Assistant │───────────────────────▶│ MCP Server   │
└──────────────┘                        └──────────────┘
                                               │
                                               │ 2. Redirect
                                               ▼
                                        ┌──────────────┐
                                        │  Promptsy    │
                                        │  Consent     │
                                        └──────────────┘
                                               │
                                               │ 3. Approve
                                               ▼
┌──────────────┐    4. Access token    ┌──────────────┐
│ AI Assistant │◀──────────────────────│ MCP Server   │
└──────────────┘                        └──────────────┘
  1. Request: AI assistant asks to use Promptsy tools
  2. Redirect: You're sent to Promptsy to authorize
  3. Approve: You review and approve the permissions
  4. Token: The assistant receives an access token

Scopes​

When authorizing, you'll see these permission scopes:

ScopePermissionRequired For
prompts:readView your prompts and collectionsbrowse_prompts
prompts:writeCreate and save promptssave_prompt
account:readView your tier and creditsCredit balance display

For full functionality, grant all three scopes. You can revoke access anytime.

Minimal Access​

If you only want to browse:

  • Grant only prompts:read
  • save_prompt will not work

Token Lifecycle​

Access Token​

  • Duration: 1 hour
  • Refresh: Automatic via refresh token
  • Storage: Stored securely by the AI assistant

Refresh Token​

  • Duration: 30 days
  • Purpose: Get new access tokens without re-authorizing
  • Rotation: New refresh token issued with each use

Token Expiration​

When a token expires:

  1. The MCP server returns a TOKEN_EXPIRED error
  2. The AI assistant uses the refresh token
  3. A new access token is issued
  4. The request is retried automatically

If the refresh token is also expired, you'll need to re-authorize.

The consent screen shows:

  • App Name: The AI assistant requesting access
  • Scopes: What permissions are requested
  • Your Account: Which Promptsy account is being authorized

Approve​

Click Approve to grant access. The AI assistant can now use the requested tools.

Deny​

Click Deny to reject the request. No access is granted.

Managing Connections​

View Connected Apps​

  1. Go to promptsy.dev/settings
  2. Scroll to Connected Apps
  3. See all AI assistants with access

Revoke Access​

To disconnect an AI assistant:

  1. Go to Connected Apps
  2. Find the app to revoke
  3. Click Revoke Access

The assistant will immediately lose access. You can re-authorize later if needed.

Security Best Practices​

Review Before Approving​

Always check:

  • The app name matches what you expect
  • The scopes are appropriate
  • You're logged into the correct Promptsy account

Revoke Unused Connections​

Periodically review connected apps and revoke any you no longer use.

Use Trusted Clients​

Only authorize AI assistants from trusted sources. The MCP protocol is powerful—only connect to apps you trust.

OAuth 2.1 Details​

For developers building MCP clients:

Endpoints​

EndpointURL
Authorizationhttps://mcp.promptsy.dev/authorize
Tokenhttps://mcp.promptsy.dev/oauth/token

Grant Type​

  • Authorization Code (with PKCE recommended)

Token Response​

{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBh...",
  "scope": "prompts:read prompts:write account:read"
}

Using the Token​

Include in the Authorization header:

Authorization: Bearer eyJhbGc...

Troubleshooting​

"Authorization Failed"​

  1. Clear cookies and try again
  2. Make sure you're logged into Promptsy
  3. Check for popup blockers

"Invalid Token"​

  1. The token may have expired
  2. Wait for automatic refresh, or
  3. Re-authorize the connection

"Insufficient Scope"​

The tool requires a scope you didn't grant:

  1. Revoke the existing connection
  2. Re-authorize with the required scope

Next Steps​