ChatGPT Connector OAuth: Redirect URLs and Sign-In

Every custom ChatGPT connector that connects to a protected resource uses OAuth 2.0 for authorization. When a user activates a connector in ChatGPT, the platform redirects them to a sign-in page, they approve access, and an authorization code comes back to a redirect URL you register. Your server exchanges that code for an access token, which it uses to make API calls on ChatGPT's behalf. Getting the redirect URL right is the most common source of OAuth errors in connector development. Tools like fenbs use the same OAuth standard for their own MCP connection and record integration decisions in a place that persists across sessions.

This page explains the OAuth flow for ChatGPT connectors, how to set up the redirect URL, and what causes the most common errors.

How OAuth works in a ChatGPT connector

The ChatGPT connector platform uses OAuth 2.0 Authorization Code flow. When a user triggers a connector for the first time, ChatGPT redirects them to the authorization endpoint of the service being connected. The user signs in and approves the requested scopes. The service then redirects back to a URL you registered, with an authorization code in the query string.

Your connector server receives that code, calls the token endpoint to exchange it for an access token and a refresh token, and stores the tokens. When ChatGPT calls the connector for data, your server uses the access token to call the target API. When the access token expires, your server uses the refresh token to get a new one.

Registering and matching the redirect URL

The redirect URL is the most common source of OAuth errors. The URL you register in the target service's OAuth app settings must match the URL ChatGPT uses after authorization exactly. Most OAuth providers enforce exact string matching, including the scheme, domain, path, and trailing slash.

When building a connector, you register the redirect URL in two places: in the target service's OAuth app settings (for example, in Asana's developer portal, GitHub's app settings, or Microsoft Entra), and in the ChatGPT connector registration. Both must match. During local development, use your tunnel URL (from a service like ngrok) rather than localhost, because ChatGPT cannot reach localhost directly.

A quick way to verify the redirect URL that ChatGPT actually sends: check your server logs when the redirect arrives. The redirect_uri parameter in the request will show the exact string ChatGPT used. Compare it character by character with what you registered.

The authorization flow step by step

1. User triggers the connector in ChatGPT. The platform builds an authorization URL with your client_id, redirect_uri, scope, and a state parameter for CSRF protection.
2. The user signs in at the authorization endpoint of the target service and approves the requested scopes.
3. The service redirects to your redirect_uri with an authorization code and the same state value.
4. Your server validates the state, then calls the token endpoint with the code, client_id, client_secret, and redirect_uri.
5. The token endpoint returns an access token and usually a refresh token. Store these for that user.
6. ChatGPT calls your connector endpoint. Your server uses the access token to call the target API and returns the result.

Common OAuth errors and what causes them

• redirect_uri_mismatch: the redirect URL in the token request does not match the registered URL. Check both the OAuth app settings and the ChatGPT connector registration.
• invalid_client: the client_id or client_secret is wrong. Check that you copied them correctly from the OAuth app settings.
• invalid_grant: the authorization code has expired or been used. Codes are typically single-use and short-lived (often 60 seconds). If the code expired before your server exchanged it, the user needs to re-authorize.
• access_denied: the user declined the authorization. Your connector should handle this gracefully rather than showing a raw error.
• Token expiry 401: the access token expired and was not refreshed. Make sure your server handles token refresh before calling the API.

Security checks for your connector

A few security practices are worth enforcing during connector development.

• Validate the state parameter: always check that the state value returned with the code matches the one you sent. This prevents CSRF attacks.
• Store tokens securely: do not log access tokens or refresh tokens. Store them in a secrets manager or an encrypted database field.
• Request minimum scopes: only request the OAuth scopes your connector actually needs. Avoid requesting write permissions if you only need read access.
• HTTPS only: your connector endpoint must be HTTPS. Never accept OAuth callbacks on plain HTTP.

fenbs as a working example

fenbs uses the same OAuth 2.0 Authorization Code flow with PKCE for its own MCP sign-in. When you connect ChatGPT to fenbs from the Integrations page, ChatGPT redirects you to the fenbs authorization page, you sign in, approve access, and a token is issued. The token lasts one hour; a refresh token keeps the connection alive without requiring a new sign-in.

This is how the fenbs connector works as a real example of the flow described above. For privacy considerations when building or using OAuth connectors, see chatgpt connectors privacy. For a broader overview of what ChatGPT connectors can do, see chatgpt connectors and apps.

How to do this with fenbs

1. Create a free account. One person is free with no credit card.
2. Add the connector project to fenbs. Write the goal and add the integration tasks.
3. Write Decisions and rules for the agreed OAuth choices: scope selection, token storage strategy, error handling approach.
4. Connect ChatGPT to fenbs from Integrations using the OAuth flow described on that page.
5. At the start of each development session ask ChatGPT to read the fenbs context. Before stopping, ask it to record any new decisions about the OAuth setup.

For troubleshooting connector issues beyond OAuth, see chatgpt connectors not working.