Skip to main content

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

1

Access API Settings

Log in to app.sesametime.com and navigate to Settings > Integrations > API
2

Create a New Token

Click Create New Token
3

Copy Your Token

Copy the token, you can use the copy icon
4

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:
  1. Go to Settings > Integrations > API
  2. Find the token to revoke
  3. Click the delete button
  4. Confirm the action
Revoking a token immediately invalidates it. Any applications using that token will receive 401 Unauthorized errors.

Authentication Errors

StatusErrorCauseSolution
401UnauthorizedMissing or invalid tokenCheck token is correct and not deleted
401Token ExpiredToken has been revokedGenerate a new token
  1. Check token format: Ensure the header is exactly Authorization: Bearer YOUR_TOKEN (note the space after “Bearer”)
  2. Verify token is active: Check in the dashboard that the token hasn’t been deleted
  3. Check region: Ensure you’re using the correct API region for your account
  4. Check for typos: Copy the token again from the dashboard
  5. 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