CitoHRCitoHR
API Reference

Authentication

All API requests require authentication using session-based authentication. Learn how to authenticate with the CitoHR API.

Session-Based Authentication

CitoHR uses NextAuth.js for authentication. All API requests require a valid session cookie. When making requests from a browser, cookies are automatically included. For server-to-server requests, you'll need to include the session cookie in your requests.

Include the session cookie in your requests: 

Cookie: next-auth.session-token=YOUR_SESSION_TOKEN

Base URL

All API requests should be made to your organization's subdomain: 

https://{your-subdomain}.citohr.com/api

Or if using the main domain: 

https://app.citohr.com/api

Authentication Flow

To authenticate:

  1. Log in to your CitoHR account through the web interface
  2. Your browser will receive a session cookie
  3. Include this cookie in subsequent API requests
  4. The session is valid until you log out or it expires

Programmatic Authentication

For server-to-server or programmatic access, you can authenticate by logging in and extracting the session token. Here's an example using Node.js: 

const fetch = require('node-fetch');

async function getSessionToken(email, password) {
  const baseUrl = 'https://app.citohr.com';
  
  // Step 1: Get CSRF token from NextAuth
  const csrfResponse = await fetch(`${baseUrl}/api/auth/csrf`);
  const csrfData = await csrfResponse.json();
  
  // Step 2: Sign in using NextAuth signin endpoint
  const signInResponse = await fetch(`${baseUrl}/api/auth/signin/credentials`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({
      email: email,
      password: password,
      csrfToken: csrfData.csrfToken,
      callbackUrl: `${baseUrl}/`,
      json: 'true'
    }),
    redirect: 'manual'
  });
  
  // Step 3: Extract session cookie from response
  const setCookieHeader = signInResponse.headers.get('set-cookie');
  if (!setCookieHeader) {
    throw new Error('No session cookie received');
  }
  
  // Extract the session token from the cookie
  const sessionMatch = setCookieHeader.match(/next-auth\.session-token=([^;]+)/) ||
                       setCookieHeader.match(/__Secure-next-auth\.session-token=([^;]+)/);
  
  if (sessionMatch) {
    return sessionMatch[1];
  }
  
  throw new Error('Failed to obtain session token');
}

// Usage
const sessionToken = await getSessionToken('your-email@example.com', 'your-password');

// Use the token in API requests
const apiResponse = await fetch('https://app.citohr.com/api/users', {
  headers: {
    'Cookie': `next-auth.session-token=${sessionToken}`
  }
});

Python Example: 

import requests

def get_session_token(email, password):
    base_url = 'https://app.citohr.com'
    session = requests.Session()
    
    # Step 1: Get CSRF token from NextAuth
    csrf_response = session.get(f'{base_url}/api/auth/csrf')
    csrf_data = csrf_response.json()
    
    # Step 2: Sign in using NextAuth signin endpoint
    sign_in_response = session.post(
        f'{base_url}/api/auth/signin/credentials',
        data={
            'email': email,
            'password': password,
            'csrfToken': csrf_data['csrfToken'],
            'callbackUrl': f'{base_url}/',
            'json': 'true'
        },
        allow_redirects=False
    )
    
    # Step 3: Extract session cookie
    # NextAuth sets the cookie automatically in the session
    session_token = session.cookies.get('next-auth.session-token') or                    session.cookies.get('__Secure-next-auth.session-token')
    
    if session_token:
        return session_token
    
    raise Exception('Failed to obtain session token')

# Usage
session_token = get_session_token('your-email@example.com', 'your-password')

# Use the token in API requests
headers = {
    'Cookie': f'next-auth.session-token={session_token}'
}
response = requests.get('https://app.citohr.com/api/users', headers=headers)

Important Security Notes:

  • Never hardcode credentials in your code
  • Store credentials securely using environment variables or a secrets manager
  • Session tokens expire - implement token refresh logic
  • Use HTTPS for all API requests
  • Consider implementing retry logic for expired sessions

Authorization & Roles

Different API endpoints require different roles:

  • USER - Basic user access to own data
  • MANAGER - Access to team member data
  • ADMIN - Full organization access

If you don't have the required role, you'll receive a 403 Forbidden response.

Error Responses

Common authentication errors:

  • 401 Unauthorized - No valid session or session expired
  • 403 Forbidden - Valid session but insufficient permissions
  • 500 Internal Server Error - Server error during authentication