Create a Custom Passport

Create a Custom Passport in Appspace to securely connect custom widgets to third-party OAuth services. A Custom Passport stores reusable credentials and handles the OAuth flow for any compatible provider, allowing administrators to extend Appspace beyond built-in integrations without custom development.

Prerequisites

Before starting, ensure the following are in place.

• The Appspace user account has the Account Owner, Platform Administrator, or Location Publisher role.
• An OAuth application is registered with the third-party provider, and the Client ID and Client Secret have been obtained.
• The redirect URL in the third-party OAuth application points to the Appspace OAuth Integration Service callback endpoint.
• The provider's Authentication URL and Token URL are available.
• Optionally, the provider's Profile URL and the JSONPath expressions for extracting the connected user's email, ID, and display name from the profile response are available.

Create a Custom Passport

Follow the instructions below to create a Custom Passport using OAuth credentials from a third-party provider.

1. Log in to the Appspace console.
2. Click Integrations from the ☰ Appspace menu, and click the Passports tab.
3. Click the Add split button, and select Add Passport.
4. In the Create a passport screen, select Create Custom Passport. The Custom Passport modal is displayed.
5. In the Display Name field, enter a descriptive name for the passport. This field is required.
6. Optionally, click the Icon to upload a custom image for the passport. The default is a gear icon.
7. In the Identifier field, review the kebab-cased identifier. This value is auto-generated from the display name and is used for system integration. Click the refresh icon to regenerate the identifier from the current display name.

   Note

   The identifier is prefixed with custom: and must be unique. The value can be edited if a specific identifier is required.

8. In the Description field, enter a brief description of the integration. This field is optional.
9. In the Category drop-down, select a category. The default value is Custom. The following categories are available:
   • Custom
   • Publishing
   • Delegations
   • Calendar
   • Library
   • Social
   • Dashboard
   • Conferencing
   • People
   • Places
10. In the Authentication Type drop-down, confirm OAuth is selected.
11. Under the OAuth Configuration section, configure the following fields:
    • Client ID — Required. OAuth Client ID issued by the third-party provider.
    • Client Secret — Required. OAuth Client Secret issued by the third-party provider. Click the eye icon to show or hide the value.
    • Authentication URL — Required. OAuth authorization endpoint where users grant access.
    • Token URL — Required. OAuth token exchange endpoint used to retrieve access tokens.
    • Profile URL — Endpoint that returns the connected user's profile after authentication.
    • Profile Account Email Path — JSONPath expression to extract the user email from the profile response. Example: $.email.
    • Profile Account ID Path — JSONPath expression to extract the user ID from the profile response. Example: $.id.
    • Profile Account Name Path — JSONPath expression to extract the user display name from the profile response. Example: $.name.
    • Default Profile Account Email — Fallback email value used when the JSONPath expression cannot be resolved.
    • Default Profile Account ID — Fallback user ID value used when the JSONPath expression cannot be resolved.
    • Default Profile Account Name — Fallback display name used when the JSONPath expression cannot be resolved.
    • Reference Application Name — Inherits authentication URLs from an existing built-in application configuration.
    • Authentication Params Mapper — Custom parameter name mapping for the authorization URL, in JSON format.
    • Required Authentication Metadata — Comma-separated list of required fields expected in the OAuth callback response.
    • Extract Profile from ID Token — Select this checkbox to extract profile information from the ID token instead of calling the Profile URL.
    • Refresh Type — Token refresh strategy. Select None, Before Expiry (in minutes), or Periodically (in minutes).
    • Refresh Value — Refresh interval in minutes. Minimum value is 30. This field applies only when Refresh Type is set to a value other than None.
    • Scope — OAuth scopes to request from the provider.
    • Scope Separator — Character used to separate scope values. Defaults to a space.

    Note

    Provide profile JSONPath expressions whenever the third-party provider returns a user profile. This allows Appspace to display the connected account name and email on the passport edit page.

12. Click Connect.
13. Complete the authentication flow in the third-party OAuth provider's popup window. Once authentication completes, the passport status changes from Inactive to Active, and the passport edit page is displayed.

    Note

    If the OAuth flow is canceled or authentication fails, the passport remains in the Inactive state. The connection can be retried from the passport edit page by clicking Connect Account.

Related Articles

• Import a Custom Passport from JSON
• Manage a Custom Passport
• Custom Passport Configuration Reference