​
Overview

StackOne uses API key-based authentication to secure access to all endpoints. This guide explains how to use your API keys with Basic Authentication to make secure requests to the StackOne API.
Basic Authentication is one of the simplest authentication methods where credentials are sent as a Base64-encoded string in the Authorization header.

​
Prerequisites

Before using Basic Authentication, ensure you have completed these steps: ➡️ Create an API Key : Generate your API key from the StackOne Dashboard

​
Steps for Basic Authentication

1

Convert the API Key into a Base64 Encoded String

To authenticate using Basic Auth, you must convert your API key into a Base64 encoded string.
Important: The API key must be base64 encoded when using Basic authentication. You cannot use the raw API key directly.
Here are examples of how to encode your API key:Terminal/Command Line:
echo -n "your_api_key_here" | base64
Python:
import base64

api_key = 'your_api_key_here'
base64_api_key = base64.b64encode(api_key.encode()).decode()
print(base64_api_key)
JavaScript/Node.js:
const apiKey = 'your_api_key_here';
const base64ApiKey = Buffer.from(apiKey).toString('base64');
console.log(base64ApiKey);
Example: If your API key is sk_test_1234567890, the base64 encoded result would be: c2tfdGVzdF8xMjM0NTY3ODkw
2

Using the Base64 Encoded API Key for API Requests

Include the Base64 encoded API key in the Authorization header of your requests.Header Format:
Authorization: Basic <BASE64_ENCODED_API_KEY>
Complete cURL Example:
curl --request GET \
     --url 'https://api.stackone.com/accounts' \
     --header 'accept: application/json' \
     --header 'authorization: Basic c2tfdGVzdF8xMjM0NTY3ODkw'
3

Making Unified API Requests

For unified API endpoints, you’ll also need to include the account ID in the x-account-id header:
curl --request GET \
     --url 'https://api.stackone.com/unified/ats/applications' \
     --header 'accept: application/json' \
     --header 'authorization: Basic c2tfdGVzdF8xMjM0NTY3ODkw' \
     --header 'x-account-id: your_account_id_here'
Replace your_account_id_here with the actual account ID obtained from the List Accounts endpoint.
4

Using StackOne SDKs with Basic Authentication

StackOne provides official SDKs for multiple programming languages that simplify API integration and handle authentication automatically. Here’s how to initialize each SDK with your API key:
import { StackOne } from '@stackone/stackone-client-ts';

// Initialize the StackOne client with your API credentials
const stackOne = new StackOne({
  security: {
    username: "your_api_key_here",
    password: "",
  },
});

// Example: List accounts
const accounts = await stackOne.accounts.list();

// Example: Make a unified API request
const applications = await stackOne.ats.applications.list({
  accountId: 'your_account_id_here'
});
The SDKs automatically handle Base64 encoding and proper Authorization header formatting for HTTP Basic Authentication. Provide your raw API key in the username field and leave password empty when initializing the client.

​
Security Best Practices

Store API Keys Securely: Never expose API keys in client-side code, version control, or public repositories. Store them in secure locations such as environment variables or key vaults.
  • Use environment variables to pass API keys to your application
  • Rotate API keys regularly for enhanced security
  • Use API key scopes to limit permissions when possible
  • Monitor API key usage through the StackOne Dashboard

​
Next Steps

After setting up Basic Authentication:
  1. Making Your First API Request - Step-by-step examples for common API operations
  2. Explore API Endpoints - Browse available Platform API endpoints
  3. Try Unified APIs - Start with ATS, HRIS, CRM or other unified APIs
  4. Use SDKs - Simplify integration with official SDKs
  5. Set up Webhooks - Get real-time updates from connected providers

​
Additional Resources