SDK Integration

This guide is for developers embedding Compass into a third-party application — an intranet, mobile app, or partner portal — using the Compass SDK. The integration uses OAuth2.0 to authenticate users silently, so SDRs, agents, and partners access Compass without a separate login.

Prerequisites

Contact the Xoxoday team to obtain your Client ID and Client Secret. Store these securely — they are required for every step below.

Base URL

All OAuth APIs use the following base URL, shown as {{base_url}} in the examples below:

https://accounts.getcompass.ai/chef/v1/oauth

Authentication flow

Step 1: Authorization request (one-time)

Construct the authorization URL and open it in a browser to obtain an authorization code. This is a one-time step.

{{base_url}}/authorize
  ?client_id={{your_client_id}}
  &response_type=code
  &redirect_uri={{your_redirect_uri}}
  &scope=admin_manage,admin_read,points_read,compass_integrations,user_session,points_manage

Required scopes: admin_manage, admin_read, points_read, compass_integrations, user_session, points_manage Log in to Compass, then click Allow. Copy the authorization code from the redirected URL — you’ll use it in the next step.

Step 2: Company session creation

Exchange the authorization code for a Company Access Token and Refresh Token. Endpoint:

POST {{base_url}}/token/company?token_type=company

Request body:

{
  "grant_type": "authorization_code",
  "code": "{{token_from_step_1}}",
  "redirect_uri": "{{your_redirect_uri}}",
  "client_id": "{{your_client_id}}",
  "client_secret": "{{your_client_secret}}"
}

Sample response:

{
  "access_token": "company_access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "company_refresh_token",
  "email": "user@company.com"
}

Save the access_token (Company Access Token) and refresh_token — both are required in subsequent steps.

Step 3: User session token generation

Generate a User Access Token for a specific employee using the Company Access Token. Required scopes: admin_manage, user_session, points_read, points_history_read, payments, gaming_leaderboard_mob, gaming_mobile_api, compass_integrations, compass_splash Endpoint:

POST {{base_url}}/token/create/user

Authorization header:

Authorization: Bearer {{company_access_token}}

Request body:

{
  "user_input": "{{email_of_the_user}}",
  "scope": "admin_manage,user_session,points_read,points_history_read,payments,gaming_leaderboard_mob,gaming_mobile_api,compass_integrations,compass_splash"
}

Sample response:

{
  "access_token": "user_access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "user_refresh_token"
}

Step 4: Launch Compass via WebView

Open a WebView in your application with the following URL, replacing {user_access_token} with the value from Step 3:

https://m.getcompass.ai/?url=oauth&token={user_access_token}

The user is automatically logged into Compass.

Token expiry

Company Access Token

30 days (2,592,000 sec)

User Access Token

15 days (1,296,000 sec)

Company Refresh Token

Long-lived — rotates on each refresh

Use the Token Validation endpoint to check the remaining expires_in of any company token before making downstream calls. Proactively refresh the company token before it expires using the Refresh Token endpoint.

Token management

Refresh the Company Access Token

When the Company Access Token expires, use the Refresh Token API. Endpoint:

POST {{base_url}}/token/company

Authorization header:

Authorization: Bearer {{company_access_token}}

Request body:

{
  "grant_type": "refresh_token",
  "refresh_token": "{{token_from_step_2}}",
  "client_id": "{{your_client_id}}",
  "client_secret": "{{your_client_secret}}"
}

Sample response:

{
  "access_token": "new_company_access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

Validate the Company Access Token

Use the Token Validation API to check whether the current token is still valid. Endpoint:

GET {{base_url}}/token

Authorization header:

Authorization: Bearer {{company_access_token}}

Sample response:

{
  "access_token": "new_company_access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

Logout

Call the User Logout API whenever the user logs out of the host application. Endpoint:

POST {{base_url}}/sso/logout

Authorization header:

Authorization: Bearer {{company_access_token}}

Request body:

{
  "user_input": "{{email_of_the_user}}"
}

Sample response:

{
  "data": {
    "message": "Logout Success"
  }
}

Postman collection

Use the Compass Connect Postman collection to try every API in this guide. It includes the Company Session Creation, User Session Generation, SDK Web-View, Refresh Token, Token Validation, and User Logout requests, pre-configured with collection variables.

Download the Compass Connect Postman collection

Import this file into Postman, then set the collection variables below.

Set these collection variables after importing:

Variable	Value
`base_url`	`https://accounts.getcompass.ai/chef/v1/oauth`
`client_id`	Provided by the Xoxoday team
`client_secret`	Provided by the Xoxoday team
`authorization_code`	The code from Step 1
`redirect_url`	Your configured redirect URI

Endpoint reference

API	Method	Endpoint
Company Session Creation	POST	`{{base_url}}/token/company?token_type=company`
User Session Generation	POST	`{{base_url}}/token/create/user`
SDK Web-View	GET	`https://m.getcompass.ai/?url=oauth&token={{user_access_token}}`
Refresh Token	POST	`{{base_url}}/token/company`
Token Validation	GET	`{{base_url}}/token`
User Logout	POST	`{{base_url}}/sso/logout`

{{base_url}} is https://accounts.getcompass.ai/chef/v1/oauth.

Admin hub

Programs

Surveys

Gifts

Budgets

Benefits

Finance

AI features

Reports & analytics

User management

Platform settings

Integrations

Sales incentive

User authentication

Security & compliance

Others

Prerequisites

Base URL

Authentication flow

Step 1: Authorization request (one-time)

Step 2: Company session creation

Step 3: User session token generation

Step 4: Launch Compass via WebView

Token expiry

Company Access Token

User Access Token

Company Refresh Token

Token management

Refresh the Company Access Token

Validate the Company Access Token

Logout

Postman collection

Download the Compass Connect Postman collection

Endpoint reference

​Prerequisites

​Base URL

​Authentication flow

​Step 1: Authorization request (one-time)

​Step 2: Company session creation

​Step 3: User session token generation

​Step 4: Launch Compass via WebView

​Token expiry

Company Access Token

User Access Token

Company Refresh Token

​Token management

​Refresh the Company Access Token

​Validate the Company Access Token

​Logout

​Postman collection

Download the Compass Connect Postman collection

​Endpoint reference

Prerequisites

Base URL

Authentication flow

Step 1: Authorization request (one-time)

Step 2: Company session creation

Step 3: User session token generation

Step 4: Launch Compass via WebView

Token expiry

Token management

Refresh the Company Access Token

Validate the Company Access Token

Logout

Postman collection

Endpoint reference