> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Manage your OAuth apps

An OAuth app lets an external interface sign people into your Port organization, in their own role and permissions. This page covers creating, updating, and revoking OAuth apps. For the concept and how access works, see External interfaces.

Create an OAuth app​

Registering an OAuth app scopes it to a single Port organization. Anyone who signs in through it gets access to that org's data, in their own role, nothing more.

No client secret

This OAuth flow doesn't use a client secret. It's built for external, user-facing apps rather than a trusted backend service, so Port issues only a client ID and redirect URI, nothing to store or protect.

With the Port MCP server connected to your IDE or AI agent, ask it to register an OAuth app in Port, for example:

Create an OAuth app in Port named 'My App', with redirect URI https://myapp.example.com/callback.

The agent uses the upsert_external_interface_app tool (organization admin required). It registers the app and returns a client ID and redirect URI. See Available tools for the full External interfaces tool set.

OAuth app fields​

  • Title: a name for the app, up to 255 characters. It must be unique within your organization.
  • Client ID: generated by Port, identifies the app in the OAuth flow. No client secret is issued alongside it, see No client secret above.
  • Redirect URIs: where Port sends users back after they approve access. See Redirect URI rules below.

The number of OAuth apps you can create depends on your organization's plan.

Redirect URI rules​

Port validates redirect URIs when you create or update an OAuth app:

  • Each app needs at least 1 and at most 5 redirect URIs, with no duplicates.
  • Each URI can be up to 2048 characters long.
  • URIs must use https://. http:// is allowed only for localhost and 127.0.0.1. Custom schemes, such as myapp://, aren't supported.
  • Wildcards (*) and URL fragments (#) aren't supported. Spaces and the characters {, }, |, ^, <, >, and ` are also rejected.
  • Updating an app's redirect URIs replaces the whole set. Include every URI still in use (for example localhost, preview, and published URLs), not just the new one.

When someone signs in, the redirect_uri your app sends must exactly match one of the registered URIs, including the scheme, host, port, path, and trailing slash.

Port also allows browser (CORS) requests to its API from the origins of your registered redirect URIs, so a browser-only app can call the API directly. After you add or change a redirect URI, it can take up to about 30 seconds before CORS requests from the new origin are accepted.

Token lifetime​

Port issues rotating refresh tokens to OAuth apps. A refresh token lasts at most 30 days, and expires earlier if it isn't used for 15 days. After that, the person needs to sign in again.

List, update, and revoke an OAuth app​

Revoking an OAuth app doesn't just disable it, it permanently removes the app's registration. Anyone signed in through it loses access immediately.

With the Port MCP server connected, ask it directly, for example:

List the OAuth apps in my organization.
Rename the OAuth app "My App" to "Support portal".
Revoke the OAuth app "My App".

These map to list_external_interface_apps, upsert_external_interface_app, and revoke_external_interface_app (organization admin required). See Available tools.