Getting started with the OS1 Platform

Overview

OS1 is a logistics platform that provides an extensive development framework and sandbox environment for developers to build logistics apps and solutions. This guide walks you through the steps for getting started on the OS1 Developer Portal, from creating an account to registering an app and exploring APIs.

Step 1: Sign up for an Account

To create an application, you need to create an account in the OS1 developer portal. The portal is where you will sign in, access your dashboard, and manage everything related to your OS1 development. You can sign up for an account using either your email address (personal or business) or with single sign-on (SSO) through Google or GitHub.

To create an account using your email address.

1. Open the OS1 developer portal.
2. Click Create account.
3. Click Login with email, Login with Google, or Login with GitHub.

Now that you’re signed in, the Developer Platform dashboard will open up, ready for you to start exploring.

Setting Up Your Organization

Your next step is setting up your organization and development environment. Here’s how:

1. From the developer dashboard, select Organization from the left navigation.
2. On the Create Organization page, fill in the required information. Be sure to acknowledge the requirements for registering an organization.
3. After filling everything out, click Create Organization.
4. Next, the portal will send an OTP to your email. Use this to verify your organization.

After creating and verifying your organization, the portal automatically creates a default team for you. You can rename the team to better fit your organization. We’ll go over that in the next step.

Step 3: Create a New Team and Adding Members

Now that you’ve set up your organization, you can create a team and add members.

1. First, click Team from the left navigation panel. This will take you to the Your Teams screen.
2. In the Create Team field, enter the name of the team you wish to create, then click Create Team.

3. To add team members, click Edit next to your team name.
4. In the Email field, enter the email address of the team member you wish to invite. Once you’ve entered the email, you can assign a role to your new team member. To do this, select either Admin or Developer from the Role dropdown.
5. After assigned the role, click Send Invite.

Your invited team member will receive an email with a link to create an account on the OS1 platform.

Step 4: Register an App

After setting up your team, it’s time to register your app. Follow the steps below:

1. Sign into the OS1 developer portal.
2. From the left navigation pane, select Apps.
3. Click Create your First App.
4. Fill in the following required information for your app:
   1. App Listing Name: The name of your app
   2. App Type: Web, Mobile, or Backend.
   3. Description: As short description of the app
   4. Version: The version of your app using semantic versioning formatting.
5. Web Apps: If you’re creating a Web app, complete the following information:
   5. The relative path of the app landing page. This path will be used to form the final URL while rendering the app from the console. For example: https://tenantaname.myorg.com/application/MyOrgApp/
   6. Select Console Compatible to make the app compatible with the console app launch experience.
6. Click Register App to submit registration.

📘

Accessing Web Apps from Console

After you register a Web app, you’ll be able to access them in the Console UI using the tenant ID and your console URL: https://tenantname.sandbox.getos1.com.

It takes a few minutes to finish the registration process. After successfully registering your app, you’ll be directed to the Apps overview page where you will find your app’s credentials, including your Client ID, Client Secret, Tenant URL, and Tenant ID.

Step 5: Retrieving and Using your Platform Credentials

The next step is getting your credentials which you’ll use to authenticate your apps on the platform.

View Credentials

1. Select Apps in the left navigation bar to view a list of your registered apps.
2. Click the icon under Credentials to view the following credentials for your app.
   1. App ID: The unique ID for your app
   2. Client ID and Client Secret: Generates an access token for authentication
   3. Tenant ID and Tenant URL: Specifies the path to the sandbox environment you’re using.
3. To copy your credentials, click the copy icon next to the credential.

Service and Frontend

If you register one Web app type you will receive credentials for backend and frontend.

Service (backend)

Use the Client ID and Client Secret in your backend to generate access tokens and make API calls on the platform.

Frontend (Mobile/Web)

Use the front end credentials within your front end with Authentication and Authorization (AAA) SDK to generate an OTP that gives your users access to the platform resources through your UI.

Step 6: Explore APIs

Now that you’re all set up, you can explore our APIs.

From the Developer Portal

The OS1 Developer Portal provides a comprehensive way to explore our APIs in a read-only environment with a pre-populated dataset. To try the APIs:

1. From the left navigation, select Try Our APIs.
2. Choose an API endpoint to explore and select Try It.
3. To run the API call, select Run API Call. The result will display in the Response window.

Using Postman

The OS1 Postman collection significantly simplifies the process of testing our APIs, eliminating the need to write code for each individual endpoint. You’ll use the Client ID, Client Secret, and Tenant URL obtained from the previous step to test API calls.

1. Refer to our documentation for using our Postman Collection.
2. Open Postman and enter your credentials in the provided Postman environment. These persist as saved variables in your subsequent requests and responses.
3. Try different API endpoints using the OS1 API documentation as a guide.

Vehicle Reference App

The Vehicle Management App serves as a comprehensive guide that leverages the Participant service to streamline the creation and management of a vehicle fleet. This application comprises two integral components: a frontend app, referred to as the Client, and a backend app, designated as the Server. Both components are bundled into a single repository. To access the reference application, visit our Github repository at https://github.com/OS1-logistics/vehicle-reference-app.

Now you’re fully equipped to explore, experiment, and build with the OS1 Platform. After developing and testing your app locally, you can come back to the portal to submit it for review and eventual publishing.