Basic Auth with API Keys

Complete guide to using API keys for basic authentication with the StackOne API

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:

   TypeScript

   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'
   });
   

   Ruby

   require 'stackone_client'
   
   # Initialize the StackOne client with your API key
   s = ::StackOne::StackOne.new(
     security: Models::Shared::Security.new(
       password: "",
       username: "your_api_key_here",
     ),
   )
   
   # Example: List accounts
   res = s.accounts.list_linked_accounts()
   if ! res.linked_accounts_paginated.nil?
     # handle response
   end
   
   # Example: Make a unified API request
   req = Models::Operations::AtsListApplicationsRequest.new(
     x_account_id: "your_account_id_here",
   )
   res = s.ats.list_applications(req)
   if ! res.applications_paginated.nil?
     # handle response
   end
   

   PHP

   <?php
   require_once 'vendor/autoload.php';
   
   use StackOne\client;
   use StackOne\client\Models\Components;
   
   // Initialize the StackOne client with your API credentials
   $sdk = client\StackOne::builder()
       ->setSecurity(
           new Components\Security(
               username: 'your_api_key_here',
               password: '',
           )
       )
       ->build();
   
   // Example: List accounts
   $result = $sdk->accounts->listLinkedAccounts();
   
   // Example: Make a unified API request
   $result = $sdk->ats->listApplications(
       xAccountId: 'your_account_id_here',
   );
   ?>
   

   Java

   import com.stackone.stackone_client_java.StackOne;
   import com.stackone.stackone_client_java.models.components.Security;
   import com.stackone.stackone_client_java.models.operations.ListLinkedAccountsResponse;
   import com.stackone.stackone_client_java.models.operations.AtsListApplicationsResponse;
   
   // Initialize the StackOne client with your API credentials
   StackOne sdk = StackOne.builder()
       .security(Security.builder()
           .username("your_api_key_here")
           .password("")
           .build())
       .build();
   
   // Example: List accounts
   ListLinkedAccountsResponse res = sdk.accounts().listLinkedAccounts()
       .call();
   
   // Example: Make a unified API request
   AtsListApplicationsResponse res = sdk.ats().listApplications()
       .xAccountId("your_account_id_here")
       .call();
   

   C#

   using StackOneHQ.Client;
   using StackOneHQ.Client.Models.Components;
   using StackOneHQ.Client.Models.Operations;
   
   // Initialize the StackOne client with your API credentials
   var sdk = new StackOneHQClient(security: new Security() {
       Username = "your_api_key_here",
       Password = "",
   });
   
   // Example: List accounts
   var res = await sdk.Accounts.ListLinkedAccountsAsync();
   
   // Example: Make a unified API request
   var res = await sdk.Ats.ListApplicationsAsync(new AtsListApplicationsRequest() {
       XAccountId = "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

• API Keys Management Guide
• Making Your First API Request
• StackOne API SDKs
• Rate Limiting