OAuth applications for partners

From Planfix

A partner-owned OAuth application is intended for an integration that connects to multiple Planfix accounts. The same application credentials are used for all customer accounts, while each account controls admission separately and every user consents to their own connection.

If an integration is intended for only one account, it is simpler to create an account-owned application.

Creating an application

  1. Open your partner account.
  2. Go to OAuth applications.
  3. Select Create application.
  4. Enter the name and description that users and administrators will see.
  5. Select the OAuth client type.
  6. Add the redirect URIs.
  7. Select the minimum required REST API scopes.
  8. Save the application and copy its credentials.

A new application is private and requires explicit approval in every account it connects to.

OAuth client type

Type Intended applications Credentials
Public Mobile, desktop, and browser applications, and local MCP clients. A client_id only. There is no client secret; PKCE S256 is mandatory.
Confidential Server-side applications where the secret can be stored outside the user's device and client-side code. A client_id and client_secret.

The OAuth client type is separate from whether an application is published. For example, a private mobile application is a public OAuth client without a secret.

Redirect URIs

Specify every URL to which Planfix may return a user after sign-in.

  • Use https for a web service.
  • http is allowed only for loopback addresses such as localhost and 127.0.0.1.
  • A client may use a dynamic port for a loopback address, but the scheme, host, path, and query must match.
  • Do not use wildcards, URL fragments, or redirect URIs that you do not control.

Scopes

Scopes define the application's maximum permissions. Request only the access levels required from the REST API scope list.

Application scopes do not replace the user's normal permissions. Even when a scope is granted, the application can work only with data available to that user.

Changing redirect URIs or scopes creates a new approval version. Previously connected accounts must review and approve the new version, and users must connect again.

Connecting a customer account

A private partner-owned application must be explicitly approved by an administrator in every account.

  1. Open the application in your partner account.
  2. In the approval link area, enter the customer account name.
  3. Copy the generated link and send it to an administrator of that account.
  4. Ask the administrator to verify the owner, redirect URIs, and scopes, and then approve the application.
  5. After approval, users in the account can complete OAuth authorization. Each user consents separately on their own behalf.

The link opens Account management → API → OAuth and MCP applications and displays the requested application.

An administrator who is also connecting the application can select Approve and connect.

Private and published applications

Status How it is admitted to an account
Private Always requires explicit approval from an administrator of every account.
Published Available without separate approval when the account policy is Allow published applications. It still requires approval when the policy is Approved applications only.

Publication is a separate Planfix review. Before submitting an application, prepare a clear name and description, a minimal scope set, working redirect URIs, and user documentation for connecting and removing the integration. Contact Planfix Support for the publication procedure.

Connection addresses

Use the global OAuth endpoints:

Purpose Address
Authorization https://auth.planfix.com/oauth/authorize
Token https://auth.planfix.com/oauth/token
Userinfo https://auth.planfix.com/oauth/userinfo
MCP https://mcp.planfix.com/mcp

Do not add the account name to a global URL. The user selects the account on a Planfix page. The complete protocol, including resource, PKCE, token refresh, and revocation, is described in OAuth 2.0 for applications.

Managing an application

A partner can:

  • edit the name and description;
  • change redirect URIs and scopes;
  • disable and re-enable the application;
  • rotate the client secret of a confidential application;
  • generate an application approval link for a specific account.

After secret rotation, the old client secret stops working immediately. Update the secret on the integration server and never send it to users.

Disabling an application blocks OAuth authorization and its issued tokens in every account. This action affects all customers using the application.

Recommendations before launch

  • Use Authorization Code with PKCE S256 and validate state.
  • Request only the scopes you need.
  • Show the selected account to the user after sign-in.
  • Handle refresh token rotation: after a successful refresh, the previous refresh token is no longer valid.
  • Do not write tokens, authorization codes, code_verifier, or client secrets to logs.
  • Document how users can disconnect the integration and request deletion of their data.
  • Test approval revocation, application disablement, and reconnection scenarios.

Go To