Import a Custom Passport in Appspace from a pre-configured JSON file to skip manual entry of OAuth fields. This method is used to migrate passport configurations between environments, or to onboard a new integration shared by another administrator.
Prerequisites
Before starting, ensure the following are in place.
- The Appspace user account has the Account Owner, Platform Administrator, or Location Publisher role.
- A Custom Passport JSON file matching the supported schema is available. A template can be downloaded from the import modal.
- The redirect URL registered with the third-party OAuth provider matches the Appspace OAuth Integration Service callback endpoint.
Important
Files exported from another Appspace environment have sensitive fields such as Client Secret cleared for security. These values must be re-entered before connecting the imported passport.
Import a Custom Passport
Follow the instructions below to create a Custom Passport from a JSON file.
- Log in to the Appspace console.
- Click Integrations from the ☰ Appspace menu, and click the Passports tab.
- Click the Add split button, and select Import Passport.
- In the import modal, click Download JSON template if a prepared file is not yet available. See Sample JSON Structure for an example.
- Click Choose file, and select the Custom Passport JSON file.
- Review the pre-filled fields in the Create Custom Passport modal that opens.
- Enter values for any cleared fields, such as Client Secret.
- Click Connect.
- Complete the authentication flow in the third-party OAuth provider's popup window. The passport status changes to Active after authentication completes successfully.
Note
The JSON file format does not include a passport icon. Icons can be added after the passport is created, from the passport edit page.
Sample JSON Structure
The following sample shows a valid Custom Passport JSON file structure. Replace placeholder values with credentials and URLs from the OAuth provider.
{
"name": "GitHub Integration",
"categoryType": "custom",
"isCustomApplication": true,
"customApplicationInfo": {
"prefix": "custom",
"applicationName": "custom:test-custom",
"name": "test-custom",
"displayName": "GitHub Integration",
"description": "Custom GitHub OAuth integration",
"parentName": "custom",
"categoryType": "custom",
"authenticationType": "oauth",
"metadata": {
"clientId": "YOUR_CLIENT_ID",
"clientSecret": "YOUR_CLIENT_SECRET",
"authenticationUrl": "https://github.com/login/oauth/authorize",
"tokenUrl": "https://github.com/login/oauth/access_token",
"profileUrl": "https://api.github.com/user",
"scope": "user:email read:user",
"refreshValue": 30
}
},
"schema": {
"version": "1.0",
"authenticationType": "OAuth",
"requiresConnection": true,
"inputs": [
{
"name": "clientId",
"type": "text",
"label": "Client ID",
"description": "OAuth client ID",
"isEditable": true,
"validation": {
"required": true
}
},
{
"name": "clientSecret",
"type": "password",
"label": "Client Secret",
"description": "OAuth client secret",
"isEditable": true,
"validation": {
"required": true
}
},
{
"name": "authenticationUrl",
"type": "text",
"label": "Authentication URL",
"description": "OAuth authorization endpoint (required unless referenceApplicationName is set)",
"isEditable": true,
"validation": {
"required": true,
"isUrl": true
}
},
{
"name": "tokenUrl",
"type": "text",
"label": "Token URL",
"description": "OAuth token endpoint (required unless referenceApplicationName is set)",
"isEditable": true,
"validation": {
"required": true,
"isUrl": true
}
},
{
"name": "profileUrl",
"type": "text",
"label": "Profile URL",
"description": "User profile endpoint",
"isEditable": true,
"validation": {
"isUrl": true
}
},
{
"name": "profileAccountEmailPath",
"type": "text",
"label": "Profile Account Email Path",
"description": "JSONPath to extract email from profile response",
"isEditable": true
},
{
"name": "profileAccountIdPath",
"type": "text",
"label": "Profile Account ID Path",
"description": "JSONPath to extract user ID from profile response",
"isEditable": true
},
{
"name": "profileAccountNamePath",
"type": "text",
"label": "Profile Account Name Path",
"description": "JSONPath to extract user name from profile response",
"isEditable": true
},
{
"name": "defaultProfileAccountEmail",
"type": "text",
"label": "Default Profile Account Email",
"description": "Fallback email value if not found in profile",
"isEditable": true
},
{
"name": "defaultProfileAccountId",
"type": "text",
"label": "Default Profile Account ID",
"description": "Fallback user ID value if not found in profile",
"isEditable": true
},
{
"name": "defaultProfileAccountName",
"type": "text",
"label": "Default Profile Account Name",
"description": "Fallback user name value if not found in profile",
"isEditable": true
},
{
"name": "referenceApplicationName",
"type": "text",
"label": "Reference Application Name",
"description": "Inherit URLs from an existing provider",
"isEditable": true
},
{
"name": "authenticationParamsMapper",
"type": "text",
"label": "Authentication Params Mapper",
"description": "Custom parameter name mapping for auth URL (JSON format)",
"isEditable": true
},
{
"name": "requiredAuthenticationMetadata",
"type": "text",
"label": "Required Authentication Metadata",
"description": "Required fields in OAuth callback (comma-separated)",
"isEditable": true
},
{
"name": "extractProfileFromIdToken",
"type": "boolean",
"label": "Extract Profile from ID Token",
"description": "Extract profile from ID token instead of calling profileUrl",
"isEditable": true,
"model": false
},
{
"name": "refreshType",
"type": "dropdown",
"label": "Refresh Type",
"description": "Token refresh strategy",
"isEditable": true,
"options": {
"items": [
{
"value": "",
"label": "None"
},
{
"value": "beforeExpiryInMinutes",
"label": "Before Expiry (in minutes)"
},
{
"value": "periodicallyInMinutes",
"label": "Periodically (in minutes)"
}
]
}
},
{
"name": "refreshValue",
"type": "number",
"label": "Refresh Value",
"description": "Refresh interval in minutes (minimum 30)",
"isEditable": true,
"validation": {
"min": 30
}
},
{
"name": "scope",
"type": "text",
"label": "Scope",
"description": "OAuth scopes to request",
"isEditable": true
},
{
"name": "scopeSeparator",
"type": "text",
"label": "Scope Separator",
"description": "Character to separate scopes",
"isEditable": true,
"model": " "
}
]
}
}
Related Articles