Registering Your App

5min

Overview
The RegisterApp API allows developers to register apps with the OS1 platform. This API supports three app types, including web, mobile, or backend.
Endpoint: POST /developer/apps
Query Parameters
Parameter
Description
organizationId*﻿
The unique ID of the organization.
teamId*﻿
The unique ID of the team. 
﻿
Register App Attributes
Parameter
Description
displayName*﻿
The name that will be displayed to the users in the Console and Marketplace. 
type*﻿
The type of application. The acceptable values are:
WEB
BACKEND
MOBILE
﻿
listingId*﻿
The unique human-readable identifier of the application.
version*﻿
The semver version of the application.
isConsoleCompatible*﻿
Specifies if the application is console compatible. The acceptable boolean values are:
true
false
This should be set to true if an app has to be displayed in the Console. 
visibility
Specifies if the app is visible to all organizations or a few organizations in the Marketplace. 
visibility.isPrivate
Specifies if the application is visible publicly or for subscription. This value should be false if the app is visible in the Marketplace. 
visibility.permissionType
This is only applicable when isPrivate is false.
Determines whether the selected orgs are permitted from viewing the application in the Marketplace. 
Acceptable values: 
ALLOW  
DENY
visibility.orgIdentifiers
Only applicable when isPrivate is false.
Provides a list of organization short names where a given permission is applied.
url
A dictionary of various supported URLs for the application.
url.relativePath
The relative path of a web application that will be appended after the base tenant URL. 
url.stackId
Use * for URLs that should be the same across all stacks. Specify the stackId for stack-specific URLs.
url.server
The backend server URL will serve as baseURL for app webhooks to receive notifications.
url.interface
Specifies the URL of the main page of the app. If there is no homepage, leave this value empty. If the homepage is the same as the relative path, use "/".
url.admin
The URL to the admin interface, if it exists.
url.setting
The URL for app settings page, if it exists.
url.userGuide
The URL for the documentation home page, if it exists.
url.gitInfo
The URL for the git repository, if it exists.
shortDescription*﻿
A short description of the application for display on the Marketplace.
longDescription
An extended description of the application for display on the Marketplace.
categories*﻿
The categories that the application belongs to. This is a free-form, tag-like set of strings. Some example categories include Dispatch and Routing. 
menu*﻿
Controls how a sub-menu of an app is displayed on the Console. Only applicable to Console compatible applications.
menu.displayName*﻿
The name of the sub-menu item within the app. 
menu.displayOrder*﻿
Controls the listing sequence of the sub-menu within an app. Assigning a numerical value like 1, 2, 3, etc., will arrange the sub-menu in that specific order within the left navigation of the Console. If this parameter is left blank or set to '0', the sub-menu will not be displayed in the menu. 
menu. relativePath*﻿
The relative path of the sub-menu item.
packageName
The package name for mobile or web apps. 
MOBILE Apps:  Specify the packageName in the format common to the platform (e.g., com.example.appname). If the packageName is left undefined, the API will use the listingId to generate the URL. For example:
com.getos1.mobile-vans-trackers://auth-apps.getos1.com/auth/realms/dpdevsb1/android/com.getos1.mobile-vans-trackers/callback
com.getos1.mobile-vans-trackers://auth-apps.getos1.com/auth/realms/dpdevsb1/ios/com.getos1.mobile-vans-trackers/callback

WEB Apps: Use the packageName to define a custom redirect URLs (e.g., .com.example.test) for mobile apps. If the packageName is left undefined, then the API will not generate a redirect URL. This should be used only if your web and mobile app use the same keys. 
﻿
﻿Required Attributes﻿
(*) Indicates that the attribute is required. 
﻿
Example Request 
The following request registers an app for tracking vehicles. 
WEB App
MOBILE App
{
	"displayName": "Vans Tracker",
	"type": "MOBILE",
	"listingId": "mbbile-vans-trackers",
	"version": "1.0.2",
	"isConsoleCompatible": false,
	"isPrivate": true,
	"url": {
		"relativePath": "/vantrackers",
		"stackId": "*",
		"server": "your-kubernetes-cluster.svc.cluster.local",
		"interface": "/",
		"admin": "admin",
		"setting": "settings",
		"userGuide": "docs",
		"gitInfo": "https://github.com/your-org/your-repo"
	},
	"shortDescription": "A truck tracker that allows you to track your trucks.",
	"longDescription": "Dig deep into the details of your truck maintenance schedules as well as locations. Receive notifications when a vehicle hits a maintenance milestone.",
	"categories": [
		"vehicle",
		"tracking"
	],
	"menu": [{
		"displayName": "Inventory",
		"displayOrder": 4,
		"relativePath": "inventory"
	}],
     "packageName": "com.example.vantracker"
}
{
	"displayName": "Vans Tracker",
	"type": "MOBILE",
	"listingId": "mbbile-vans-trackers",
	"version": "1.0.2",
	"isConsoleCompatible": false,
	"isPrivate": true,
	"url": {
		"relativePath": "/vantrackers",
		"stackId": "*",
		"server": "your-kubernetes-cluster.svc.cluster.local",
		"interface": "/",
		"admin": "admin",
		"setting": "settings",
		"userGuide": "docs",
		"gitInfo": "https://github.com/your-org/your-repo"
	},
	"shortDescription": "A truck tracker that allows you to track your trucks.",
	"longDescription": "Dig deep into the details of your truck maintenance schedules as well as locations. Receive notifications when a vehicle hits a maintenance milestone.",
	"categories": [
		"vehicle",
		"tracking"
	],
	"menu": [{
		"displayName": "Inventory",
		"displayOrder": 4,
		"relativePath": "inventory"
	}],
     "packageName": "com.example.vantracker"
}
﻿
Example Response:
WEB 
MOBILE
{
    "data": {
        "id": {
            "appId": "app:c2a99e35-afc2-5407-8efb-c5f189600f13",
            "appVersionId": "appversion:04348faf-f185-52a3-a68a-8002f7307bd5"
        }
    },
    "request": {
        "url": "/developer/apps?organizationId=af86b55e-45c9-41ee-95f7-d335d366022f&teamId=87dd5441-e8c4-4171-ba24-79f47992ba9b",
        "method": "POST",
        "params": {},
        "query": {
            "organizationId": "af86b55e-45c9-41ee-95f7-d335d366022f",
            "teamId": "87dd5441-e8c4-4171-ba24-79f47992ba9b"
        },
        "body": {
            "displayName": "Vans Tracker",
            "type": "MOBILE",
            "listingId": "mbbile-vans-trackers",
            "version": "1.0.2",
            "isConsoleCompatible": false,
            "url": {
                "relativePath": "/vantrackers",
                "stackId": "*",
                "server": "your-kubernetes-cluster.svc.cluster.local",
                "interface": "/",
                "admin": "admin",
                "setting": "settings",
                "userGuide": "docs",
                "gitInfo": "https://github.com/your-org/your-repo"
            },
            "shortDescription": "A truck tracker that allows you to track your trucks.",
            "longDescription": "Dig deep into the details of your truck maintenance schedules as well as locations. Receive notifications when a vehicle hits a maintenance milestone.",
            "categories": [
                "vehicle",
                "tracking"
            ],
            "menu": [
                {
                    "displayName": "Inventory",
                    "displayOrder": 4,
                    "relativePath": "inventory"
                }
            ]
        }
    }
}
{
    "data": {
        "id": {
            "appId": "app:c2a99e35-afc2-5407-8efb-c5f189600f13",
            "appVersionId": "appversion:04348faf-f185-52a3-a68a-8002f7307bd5"
        }
    },
    "request": {
        "url": "/developer/apps?organizationId=af86b55e-45c9-41ee-95f7-d335d366022f&teamId=87dd5441-e8c4-4171-ba24-79f47992ba9b",
        "method": "POST",
        "params": {},
        "query": {
            "organizationId": "af86b55e-45c9-41ee-95f7-d335d366022f",
            "teamId": "87dd5441-e8c4-4171-ba24-79f47992ba9b"
        },
        "body": {
            "displayName": "Vans Tracker",
            "type": "MOBILE",
            "listingId": "mbbile-vans-trackers",
            "version": "1.0.2",
            "isConsoleCompatible": false,
            "url": {
                "relativePath": "/vantrackers",
                "stackId": "*",
                "server": "your-kubernetes-cluster.svc.cluster.local",
                "interface": "/",
                "admin": "admin",
                "setting": "settings",
                "userGuide": "docs",
                "gitInfo": "https://github.com/your-org/your-repo"
            },
            "shortDescription": "A truck tracker that allows you to track your trucks.",
            "longDescription": "Dig deep into the details of your truck maintenance schedules as well as locations. Receive notifications when a vehicle hits a maintenance milestone.",
            "categories": [
                "vehicle",
                "tracking"
            ],
            "menu": [
                {
                    "displayName": "Inventory",
                    "displayOrder": 4,
                    "relativePath": "inventory"
                }
            ]
        }
    }
}
﻿
﻿
❗ Unauthorized Error ﻿
An unauthorized error occurs when using an incorrect orgId or teamId. Confirm you are using the correct orgId or teamId.
﻿

Parameter	Description
organizationId*	The unique ID of the organization.
teamId*	The unique ID of the team.

Parameter	Description
displayName*	The name that will be displayed to the users in the Console and Marketplace.
type*	The type of application. The acceptable values are: WEB BACKEND MOBILE
listingId*	The unique human-readable identifier of the application.
version*	The semver version of the application.
isConsoleCompatible*	Specifies if the application is console compatible. The acceptable boolean values are: true false This should be set to true if an app has to be displayed in the Console.
visibility	Specifies if the app is visible to all organizations or a few organizations in the Marketplace.
visibility.isPrivate	Specifies if the application is visible publicly or for subscription. This value should be false if the app is visible in the Marketplace.
visibility.permissionType	This is only applicable when isPrivate is false. Determines whether the selected orgs are permitted from viewing the application in the Marketplace. Acceptable values: ALLOW DENY
visibility.orgIdentifiers	Only applicable when isPrivate is false. Provides a list of organization short names where a given permission is applied.
url	A dictionary of various supported URLs for the application.
url.relativePath	The relative path of a web application that will be appended after the base tenant URL.
url.stackId	Use * for URLs that should be the same across all stacks. Specify the stackId for stack-specific URLs.
url.server	The backend server URL will serve as baseURL for app webhooks to receive notifications.
url.interface	Specifies the URL of the main page of the app. If there is no homepage, leave this value empty. If the homepage is the same as the relative path, use "/".
url.admin	The URL to the admin interface, if it exists.
url.setting	The URL for app settings page, if it exists.
url.userGuide	The URL for the documentation home page, if it exists.
url.gitInfo	The URL for the git repository, if it exists.
shortDescription*	A short description of the application for display on the Marketplace.
longDescription	An extended description of the application for display on the Marketplace.
categories*	The categories that the application belongs to. This is a free-form, tag-like set of strings. Some example categories include Dispatch and Routing.
menu*	Controls how a sub-menu of an app is displayed on the Console. Only applicable to Console compatible applications.
menu.displayName*	The name of the sub-menu item within the app.
menu.displayOrder*	Controls the listing sequence of the sub-menu within an app. Assigning a numerical value like 1, 2, 3, etc., will arrange the sub-menu in that specific order within the left navigation of the Console. If this parameter is left blank or set to '0', the sub-menu will not be displayed in the menu.
menu. relativePath*	The relative path of the sub-menu item.
packageName	The package name for mobile or web apps. MOBILE Apps: Specify the packageName in the format common to the platform (e.g., com.example.appname). If the packageName is left undefined, the API will use the listingId to generate the URL. For example: com.getos1.mobile-vans-trackers://auth-apps.getos1.com/auth/realms/dpdevsb1/android/com.getos1.mobile-vans-trackers/callback com.getos1.mobile-vans-trackers://auth-apps.getos1.com/auth/realms/dpdevsb1/ios/com.getos1.mobile-vans-trackers/callback WEB Apps: Use the packageName to define a custom redirect URLs (e.g., .com.example.test) for mobile apps. If the packageName is left undefined, then the API will not generate a redirect URL. This should be used only if your web and mobile app use the same keys.

Updated 09 May 2024

Did this page help you?

OS1 App Developer’s Guide

Automatic Creation of User Groups and Roles for Apps