Configure permissions, access, and token security

Application security is the combination of requested permissions, install eligibility, administrator access, grants, token policy, and credential custody. A secure OAuth flow can still be over-privileged if these controls are too broad.

Consent permissions

The application contract supports a list of consent-screen permissions containing a name, description, and whether the permission is custom. When omitted, identity scopes can default to openid, profile, and email in the current management contract.

For every permission:

• use a stable, specific name;
• explain what data or action it enables;
• separate read and write access;
• request it only when needed;
• avoid vague labels such as “full access”;
• remove obsolete permissions carefully after reviewing existing connections.

A consent description should help a user make an informed decision, not hide technical impact.

Install access policies

Released application management supports these policy shapes:

• public — eligible users can discover/install according to current marketplace rules;
• invite-only — limited to invited users;
• approval-required — connection requires approval;
• workspace-restricted — limited to explicit workspace IDs.

Choose the narrowest policy that fits the release stage. Use restricted or approval-based access for testing rather than making a draft integration broadly available.

Workspace restriction controls installation eligibility. It does not automatically grant the app access to workspace content.

Application administrators

Application admins can affect identity, connection, and marketplace behavior.

• Keep the list small and current.
• Use named accountable users.
• Review access periodically.
• Remove former maintainers promptly.
• Separate app administration from workspace ownership.
• Require review for grants, scopes, redirects, secrets, and visibility.

Do not place admin IDs or private contacts in public-facing descriptions.

Token and session lifetimes

The current application contract includes access-token lifespan, refresh-token lifespan, and session idle timeout settings.

Use shorter access tokens and refresh only when the workflow requires continuation. Balance usability against exposure:

• access tokens should expire promptly;
• refresh tokens need stricter storage and revocation;
• idle sessions should end;
• development settings should not silently become production defaults;
• lifetime changes should be tested against existing clients.

Do not document one universal recommended number without considering the client and deployed policy.

Offline access

Offline login configuration can include:

• whether offline access is enabled;
• refresh-token expiration;
• rotation policy;
• maximum reuse count where supported.

Enable offline access only for a defined background use case. Prefer rotate-on-use where compatible, detect unexpected reuse, and revoke the token family on compromise.

A long-lived refresh token is a high-value credential even if access tokens are short-lived.

Custom token properties

Application token configuration can define custom properties sourced from user, workspace, or controlled custom mapping logic where supported.

Treat custom claims as a public contract:

• include only data the client requires;
• avoid secrets and unnecessary personal data;
• use stable names and types;
• validate array and numeric values;
• review workspace-derived claims for cross-workspace leakage;
• version breaking changes.

Never place executable or unreviewed user input into mapping logic.

Secret handling

• Store client secrets, refresh tokens, and service credentials in a secret manager.
• Never commit them or place them in Usable fragments.
• Keep secrets out of browser and mobile bundles.
• Redact authorization headers and token responses from logs.
• Use separate credentials by environment.
• Rotate after exposure or maintainer changes.
• Revoke old credentials after verifying replacement.
• Restrict outbound destinations to prevent token forwarding.

A client ID is often an identifier, not a secret. Do not treat that distinction as permission to expose associated configuration or credentials.

Review before beta or active

1. Confirm exact redirects and origins.
2. Remove unused grants.
3. Review every consent permission.
4. Confirm install policy and workspace restrictions.
5. Review administrators.
6. Test token expiry, refresh, revocation, and denial.
7. Verify secret rotation.
8. Review descriptions and icon origins for public safety.
9. Confirm support and incident ownership.
10. Promote status only after approval.

Respond to exposure

If a secret, refresh token, Device Code, or bearer credential is exposed:

1. Revoke or rotate it immediately.
2. Stop affected automation if needed.
3. Remove the exposed value from content and logs.
4. Inspect application and token activity.
5. Verify redirect, grant, scope, and admin settings.
6. Restore service with a new credential.
7. Document the incident without reproducing the secret.

Deleting a screenshot or fragment is not sufficient if the credential remains valid.

Common failures

Consent shows unexpected access

Review application permissions and custom scopes before approving. Ask the developer to narrow or explain them.

A workspace-restricted app still receives 403

Eligibility and workspace authorization are distinct. Check the connected user's workspace role and granted scopes.

Refresh stops working

The token may be expired, revoked, rotated, reused, or outside the offline policy. Reauthenticate rather than weakening rotation globally.

A browser app requires a client secret

The configuration likely uses an unsuitable confidential-client grant. Revisit application type and grant selection.

Related pages

• Choose an OAuth grant and application type
• Discover and connect marketplace apps
• Personal access tokens