Single Sign-On (SSO)

Implement SSO to allow users to authenticate into Oktopost from your application without entering credentials.

This endpoint enables you to build a Single Sign-On integration that seamlessly authenticates users into Oktopost from your application. The authentication flow uses one-time access tokens to log users in without requiring them to enter their Oktopost username and password.

This documentation covers developing an SSO integration using the Oktopost API. If you're looking to configure an existing SSO provider (like Okta or Azure AD) for your Oktopost account, please refer to our Help Center article on SSO configuration.

How It Works

The SSO authentication flow follows these steps:

Your application makes an authenticated API request to obtain a one-time login token
Your application redirects the user to Oktopost with the token
Oktopost validates the token and logs the user in
The user is redirected to the Oktopost dashboard (or a specific page if specified)

To generate a one-time access token, make an authenticated request to the token endpoint with your application's private key.

Private Key Required

The privateKey parameter is only available for authorized applications. If you want to implement SSO, please contact our team to get your application authorized.

Request

curl -u ACCOUNT_ID:API_KEY \
  "https://api.oktopost.com/v2/auth-token?privateKey=YOUR_PRIVATE_KEY"

Response

{  
    "Result": true,
    "Token": "574dac5e6bcb31.23085498b3fc1c5d3398cca07bb31e5729d3a32f"
}

The token is single-use and expires after a short period (typically 5 minutes). Generate a new token for each authentication attempt.

Redirecting the User

Once you've obtained the token, redirect the user to Oktopost using the token in the URL:

Basic Redirect

https://app.oktopost.com/auth/token/id/[TOKEN]

By default, users will land on the Oktopost dashboard after authentication.

Redirect to Specific Page

To send users to a specific page within Oktopost after login, include the _redirect parameter with the desired path:

https://app.oktopost.com/auth/token/id/[TOKEN]?_redirect=/calendar

Common redirect paths include:

/calendar - Calendar view
/messages - Message queue
/analytics - Analytics dashboard
/settings - Account settings

Example Implementation

Here's a simplified example of an SSO flow in Node.js:

// Step 1: Generate login token
const response = await fetch(
  'https://api.oktopost.com/v2/auth-token?privateKey=YOUR_PRIVATE_KEY',
  {
    headers: {
      'Authorization': 'Basic ' + Buffer.from('ACCOUNT_ID:API_KEY').toString('base64')
    }
  }
);

const data = await response.json();
const token = data.Token;

// Step 2: Redirect user to Oktopost with token
const redirectUrl = `https://app.oktopost.com/auth/token/id/${token}?_redirect=/calendar`;
// Redirect user to redirectUrl

On this page