App and Solution
Apps

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


Example Response:

WEB
MOBILE



Unauthorized Error 

An unauthorized error occurs when using an incorrect orgId or teamId. Confirm you are using the correct orgId or teamId.