> ## Documentation Index
> Fetch the complete documentation index at: https://help-empuls.xoxoday.com/llms.txt
> Use this file to discover all available pages before exploring further.
# SDK Integration
> Embed Compass in your client application using the Compass SDK so users access it seamlessly within your existing platform.
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:**
```json theme={null}
{
"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:**
```json theme={null}
{
"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:**
```json theme={null}
{
"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:**
```json theme={null}
{
"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
**30 days** (2,592,000 sec)
**15 days** (1,296,000 sec)
**Long-lived** — rotates on each refresh
Use the [Token Validation](#validate-the-company-access-token) 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](#refresh-the-company-access-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:**
```json theme={null}
{
"grant_type": "refresh_token",
"refresh_token": "{{token_from_step_2}}",
"client_id": "{{your_client_id}}",
"client_secret": "{{your_client_secret}}"
}
```
**Sample response:**
```json theme={null}
{
"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:**
```json theme={null}
{
"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:**
```json theme={null}
{
"user_input": "{{email_of_the_user}}"
}
```
**Sample response:**
```json theme={null}
{
"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.
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`.