Create and manage an application

Use an application record when an integration needs managed OAuth settings, user consent, install policies, marketplace visibility, or multiple administrators.

Start applications in draft. Registration is not publication, installation, or authorization.

Before creating

Prepare:

• a unique, user-facing name;
• an HTTPS icon URL from a controlled origin;
• short and extended descriptions;
• developer name and monitored contact email;
• categories and discovery tags;
• an application home URL where applicable;
• the application type and required grants;
• exact redirect URIs and allowed origins;
• consent permissions;
• install access policy;
• application administrators;
• token/session policy.

Do not include secrets, private callback hosts, internal diagrams, or customer data in marketplace metadata.

Create from the dashboard

1. Open /dashboard/applications.
2. Choose New application.
3. Enter the required identity and developer fields.
4. Configure the application type and grants.
5. Add exact redirects and origins.
6. Configure permissions and access policy.
7. Review token and offline-access settings.
8. Save as a draft.
9. Store any generated credential only in an approved secret manager.
10. Reopen the application and verify every field.

Available controls depend on the current account and app role.

Public metadata

The current application-management contract includes:

• name;
• icon;
• short description;
• optional Markdown longDescription;
• optional application home URL;
• developer name and contact email;
• one or more categories;
• discovery tags.

Write descriptions for users deciding whether to connect. State the purpose, expected access, supported environment, and limitations without making unverified security claims.

Administrators and ownership

Application administrators can manage sensitive configuration and lifecycle. Keep the list narrow.

• Use individual accountable identities.
• Remove administrators when responsibilities change.
• Do not grant app administration merely because someone owns a workspace.
• Require review for redirect, grant, scope, and status changes.
• Maintain a recovery owner and monitored developer contact.

Lifecycle statuses

Released application updates support:

• draft — configuration and testing;
• beta — intentionally limited release;
• active — released and available under its access policy;
• deprecated — still present but scheduled for replacement/removal;
• archived — no longer offered for normal use.

beta and active can make the app visible in the marketplace. Review metadata, security, support, and connection flow before either transition.

Test before visibility

Test in a safe environment with non-sensitive data:

1. Validate application and icon URLs.
2. Test every configured grant.
3. Confirm redirects reject unregistered destinations.
4. Review the consent screen.
5. Verify least-privilege workspace behavior.
6. Test denial, expiry, revocation, and retry paths.
7. Confirm secret rotation and support recovery.
8. Verify Installed Apps behavior where exposed.
9. Document known beta limitations.

Do not test by making an unfinished app broadly public.

Update safely

Before updating:

1. Fetch or open the current application.
2. Confirm its ID and environment.
3. Review existing live connections.
4. Change the smallest set of fields.
5. Treat redirects, grants, scopes, administrators, and status as security-sensitive.
6. Verify the saved result and run a connection smoke test.
7. Communicate breaking changes before deprecation.

The current MCP management tool limits update fields to public metadata and lifecycle fields. Use the supported dashboard or REST contract for other configuration changes.

Deprecate and archive

When retiring an application:

• stop new installs where supported;
• mark it deprecated and provide a replacement path;
• notify affected users;
• revoke credentials and sessions deliberately;
• remove unused redirects and secrets;
• verify downstream automation;
• archive only after the transition period.

Archiving a record does not guarantee every external token or copied secret has been removed.

Troubleshooting

Create is rejected

Check required fields, URL formats, developer email, category, application type, grants, token policy, and app-management permission.

App remains invisible

Draft apps are not marketplace releases. Confirm status and access policy, but do not promote solely to bypass a test limitation.

An update is forbidden

The caller may list the app but lack administrator authority to modify it.

A redirect change breaks users

Restore the last reviewed exact URI if safe, then migrate clients deliberately. Avoid wildcard redirects.

Related pages

• Choose an OAuth grant and application type
• Configure permissions, access, and token security
• Manage applications through REST and MCP