Overview
The Sesame HR API uses Bearer Token authentication. Every API request must include a valid token in the Authorization header.
Authorization: Bearer YOUR_API_TOKEN
Getting Your API Token
Create a New Token
Click Create New Token
Copy Your Token
Copy the token, you can use the copy icon
Store Securely
Save the token in your application’s secure configuration (environment variables, secrets manager, etc.)
Security Best Practices
- Never expose tokens in client-side code, logs, or version control
- Use environment variables or a secrets manager
- Create separate tokens for each integration
- Rotate tokens periodically
- Revoke tokens immediately when compromised
Making Authenticated Requests
Include your token in every API request:
curl -X GET "https://api-{region}.sesametime.com/core/v3/employees" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json"
const SESAME_API_TOKEN = process.env.SESAME_API_TOKEN;
const BASE_URL = 'https://api-{region}.sesametime.com';
async function fetchEmployees() {
const response = await fetch(`${BASE_URL}/core/v3/employees`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${SESAME_API_TOKEN}`,
'Content-Type': 'application/json'
}
});
if (!response.ok) {
throw new Error(`API Error: ${response.status}`);
}
return response.json();
}
const axios = require('axios');
const sesameClient = axios.create({
baseURL: 'https://api-{region}.sesametime.com',
headers: {
'Authorization': `Bearer ${process.env.SESAME_API_TOKEN}`,
'Content-Type': 'application/json'
}
});
// Usage
const { data } = await sesameClient.get('/core/v3/employees');
import os
import requests
class SesameAPI:
def __init__(self):
self.base_url = 'https://api-{region}.sesametime.com'
self.token = os.environ.get('SESAME_API_TOKEN')
self.headers = {
'Authorization': f'Bearer {self.token}',
'Content-Type': 'application/json'
}
def get_employees(self, **params):
response = requests.get(
f'{self.base_url}/core/v3/employees',
headers=self.headers,
params=params
)
response.raise_for_status()
return response.json()
# Usage
api = SesameAPI()
employees = api.get_employees(limit=10)
import httpx
import os
async def get_employees():
async with httpx.AsyncClient() as client:
response = await client.get(
'https://api-{region}.sesametime.com/core/v3/employees',
headers={
'Authorization': f'Bearer {os.environ["SESAME_API_TOKEN"]}',
'Content-Type': 'application/json'
}
)
response.raise_for_status()
return response.json()
<?php
class SesameAPI {
private string $baseUrl = 'https://api-{region}.sesametime.com';
private string $token;
public function __construct() {
$this->token = getenv('SESAME_API_TOKEN');
}
public function getEmployees(array $params = []): array {
$url = $this->baseUrl . '/core/v3/employees?' . http_build_query($params);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $this->token,
'Content-Type: application/json'
]
]);
$response = curl_exec($ch);
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($statusCode >= 400) {
throw new Exception("API Error: $statusCode");
}
return json_decode($response, true);
}
}
// Usage
$api = new SesameAPI();
$employees = $api->getEmployees(['limit' => 10]);
package main
import (
"encoding/json"
"fmt"
"net/http"
"os"
)
type SesameClient struct {
BaseURL string
Token string
Client *http.Client
}
func NewSesameClient() *SesameClient {
return &SesameClient{
BaseURL: "https://api-{region}.sesametime.com",
Token: os.Getenv("SESAME_API_TOKEN"),
Client: &http.Client{},
}
}
func (c *SesameClient) GetEmployees() (map[string]interface{}, error) {
req, _ := http.NewRequest("GET", c.BaseURL+"/core/v3/employees", nil)
req.Header.Set("Authorization", "Bearer "+c.Token)
req.Header.Set("Content-Type", "application/json")
resp, err := c.Client.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
return result, nil
}
require 'net/http'
require 'json'
class SesameAPI
BASE_URL = 'https://api-{region}.sesametime.com'
def initialize
@token = ENV['SESAME_API_TOKEN']
end
def get_employees(params = {})
uri = URI("#{BASE_URL}/core/v3/employees")
uri.query = URI.encode_www_form(params) if params.any?
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{@token}"
request['Content-Type'] = 'application/json'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
JSON.parse(response.body)
end
end
# Usage
api = SesameAPI.new
employees = api.get_employees(limit: 10)
Verifying Your Token
Test your token by calling the info endpoint:
curl -X GET "https://api-{region}.sesametime.com/core/v3/info" \
-H "Authorization: Bearer YOUR_API_TOKEN"
Managing Tokens
Listing Active Tokens
View all active tokens in Settings > Integrations > API. Each token shows:
- Token
- Active
- Creation Date
- Last Used Date
Revoking Tokens
To revoke a token:
- Go to Settings > Integrations > API
- Find the token to revoke
- Click the delete button
- Confirm the action
Revoking a token immediately invalidates it. Any applications using that token will receive 401 Unauthorized errors.
Authentication Errors
| Status | Error | Cause | Solution |
|---|
401 | Unauthorized | Missing or invalid token | Check token is correct and not deleted |
401 | Token Expired | Token has been revoked | Generate a new token |
Troubleshooting 401 Errors
- Check token format: Ensure the header is exactly
Authorization: Bearer YOUR_TOKEN (note the space after “Bearer”)
- Verify token is active: Check in the dashboard that the token hasn’t been deleted
- Check region: Ensure you’re using the correct API region for your account
- Check for typos: Copy the token again from the dashboard
- Check encoding: Ensure no extra characters or whitespace were added
Security Recommendations
Environment Variables
Store tokens in environment variables, never in code
Secrets Manager
Use AWS Secrets Manager, HashiCorp Vault, or similar for production
Token Rotation
Rotate tokens every 90 days as a security best practice
Audit Logs
Monitor API usage in your Sesame HR dashboard