Droppah API: Authentication Flow & Setup

Welcome to the Droppah API. This guide will walk you through the initial steps required to authenticate your application, generate the necessary tokens, and make your first API request.

Prerequisites

Before you begin, you must have your developer application approved. Once approved, you will be provided with your unique API credentials:

• Client ID

• Client Secret

Keep these credentials secure. You will use them to authenticate your application with our servers.

⚠️ Important Note on Token Expiration Both the initial access token and the x-company-token you generate during this process have a lifespan of one hour (60 minutes). Your application will need to handle token expiration gracefully by requesting new tokens when they expire.

Authentication Flow Overview

To access Droppah data, you need to generate an x-company-token. The path to get this token depends on the type of integration you are building:

1. Private Integrations: Apps built for a single company. You will authenticate your app and then immediately generate a company token.

2. Public Integrations: Third-party apps connecting to multiple Droppah customer accounts. You must first authenticate your app, redirect the user to log in and authorise your app, and then generate the company token.

Step-by-Step Guide

Step 1: Initial Application Authentication

Applies to: ALL Integrations

First, you need to authenticate your application using your Client ID and Client Secret to obtain an initial access token.

• Documentation reference: Droppah Authentication v1

Use the access token returned from this call in the Authorisation header (Bearer token) for the subsequent steps. (Remember: This token expires in 1 hour).

Step 2: User Authorisation

Applies to: PUBLIC Integrations ONLY (Private integrations can skip to Step 3)

If you are building a public integration, you must obtain permission from the Droppah user. You need to redirect the user to our authorisation URL so they can securely sign in to their Droppah account and grant your application access.

• Documentation reference: Auth - Authorise

Once the user approves the connection, you will receive an authorisation code that allows you to proceed to the next step.

Step 3: Generate the Company Token

Applies to: ALL Integrations

To interact with a company's specific rostering and people data, you must exchange your current authentication context for an x-company-token.

• Documentation reference: Auth - Company Token

Important: Store the resulting x-company-token securely. You will need to include this token in the header of almost all subsequent API requests. (Remember: This token also expires in 1 hour).

Step 4: Make your first API Call

Applies to: ALL Integrations

Now that you have your active access token and x-company-token, you are ready to start making requests.

Note on Scopes: The specific endpoints you are allowed to access depend entirely on the scopes (permissions) granted to your application during the initial setup.

As an example, if your application has been granted permission to read person data, you can test your connection by fetching a list of all people:

• Documentation reference: Get Person

Required Headers for API Calls:

• Authorization: Bearer <YOUR_ACCESS_TOKEN>

• x-company-token: <YOUR_COMPANY_TOKEN>

(If your app does not have people scopes, simply test an endpoint that matches the scopes you did request).

Next Steps

If your initial data request is successful, your integration is fully authenticated and ready to go. Check out the rest of the API Portal for documentation on managing timesheets and rostering.