Authentication

Overview

This document outlines the authentication methods and environment setup for the StableStack API.

Base URLs

The StableStack API is available in different environments. The base URL depends on your environment:

Environment	Base URL
Production	`https://api.stablestack.com`
Sandbox	`https://api-staging.stablestack.com`

The StableStack API uses Bearer token authentication. All API requests must include an Authorization header with your API token.

Getting Your API Token

Log in to your StableStack dashboard
Navigate to Settings > API Keys
Generate a new API key or use an existing one

Using the API Token

Include your API token in the Authorization header of all requests:

curl -X GET "https://api.stablestack.xyz/endpoint" \
     -H "Authorization: Bearer your_api_token_here"

Environment Detection

The API automatically detects the environment based on your API token. Each token is associated with a specific environment (Production, Staging, or Development). You don’t need to specify the environment separately - just use the appropriate base URL for your environment.

Security Best Practices

Never share your API token - Keep it secure and don’t commit it to version control
Use environment variables to store your API token
Rotate your tokens regularly for enhanced security

Example Implementation

Using Environment Variables

# Set your API token as an environment variable
export STABLESTACK_API_TOKEN="your_api_token_here"

Making Authenticated Requests

const axios = require('axios');

const api = axios.create({
  baseURL: 'https://api.stablestack.com/v1',
  headers: {
    'Authorization': `Bearer ${process.env.STABLESTACK_API_TOKEN}`,
    'Content-Type': 'application/json'
  }
});

// Example API call
async function getData() {
  try {
    const response = await api.get('/endpoint');
    return response.data;
  } catch (error) {
    console.error('API Error:', error.response.data);
  }
}

Key Management

Create new API key via your dashboard

Business API Capabilities

An active API key and approved compliance are necessary but do not grant access to every API feature. Each business has an explicit list of enabled capabilities, shared by its test and live API keys.

Capability	Endpoints covered
`wallets`	Wallet creation and wallet retrieval
`payments_stable`	Stable-to-stable payouts: wallet payouts, wallet payout methods, address validation, and payout fees
`payments_fiat`	Stable-to-fiat payouts: bank payouts, bank payout methods, bank lookup/resolution, and payout fees
`customers`	Business and individual customer management, including KYC uploads
`swaps`	Swap creation, instant swaps, and quote refresh
`transactions`	Transaction history and lookups, including customer transaction endpoints
`assets`	Asset-code discovery

No capabilities are enabled by default, including for existing businesses after the capabilities migration. A platform administrator must explicitly grant access. Business classification (api_fintech or general_business) does not grant capabilities automatically. Capability checks apply to API-key endpoints, not administrator endpoints authenticated with a session token. A merchant with wallets, payments_stable, or payments_fiat but without customers may create individual and business customers using the minimal profiles described in the customer creation references. This exception applies only to the two customer-creation POST endpoints. Minimal customer creation does not onboard the customer with payment providers or approve KYC. Merchants with payments_fiat may also update customers (PUT /api/individual-customers/{id} and PUT /api/business-customers/{id}). Stable-to-fiat bank payouts and bank payout methods return HTTP 422 with missingFields until the customer profile is complete: birth_date, address and country for individuals; business_type, business_website, registration_number, address and country for businesses. Disabled features return HTTP 403:

{
  "status": "failed",
  "message": "API capability 'wallets' is not enabled for this business.",
  "requiredCapability": "wallets"
}

Managing capabilities

These endpoints are hosted by the auth service, not the public API service, and require an authenticated session using Authorization: Bearer <session-token>:

Method	Path	Access
`GET`	`/api/users/auth/api-capabilities`	Current user’s enabled capabilities and the available catalog
`GET`	`/api/users/auth/api-capabilities/:userId`	Administrator; retrieve a merchant’s enabled capabilities
`PUT`	`/api/users/auth/api-capabilities/:userId`	Administrator; replace a merchant’s enabled capabilities

Example replacement request body:

{
  "apiCapabilities": ["wallets", "payments_stable", "transactions"]
}

The list is replaced in full, not merged. Send {"apiCapabilities":[]} to revoke all access. Missing, null, duplicate, or unknown capability values are rejected. Changes apply on the next API-key request without rotating keys or signing in again. They do not bypass compliance, key-status, or existing endpoint validation.

Deployment order

Run the auth-service migration 20261026122000_add_api_capabilities_to_users.js before deploying the new auth and API services. Grant the intended capabilities to existing merchants before enabling API-service enforcement to avoid an unplanned interruption.

Error Handling

If authentication fails, you’ll receive a 401 Unauthorized response:

{
  "status": "failed",
  "message": "Invalid or expired token",
  "error": {
    "code": "INVALID_TOKEN",
    "details": {
      "reason": "token_expired"
    }
  }
}

Rate Limiting

API tokens are subject to rate limiting. See the Error Handling documentation for more details about rate limits and error responses.

Get Started

Webhooks

Libraries

Coverage

Use Cases

Prohibited

Authentication

Overview

Base URLs

Authentication

Getting Your API Token

Using the API Token

Environment Detection

Security Best Practices

Example Implementation

Using Environment Variables

Making Authenticated Requests

Key Management

Business API Capabilities

Managing capabilities

Deployment order

Error Handling

Rate Limiting

​Overview

​Base URLs

​Authentication

​Getting Your API Token

​Using the API Token

​Environment Detection

​Security Best Practices

​Example Implementation

​Using Environment Variables

​Making Authenticated Requests

​Key Management

​Business API Capabilities

​Managing capabilities

​Deployment order

​Error Handling

​Rate Limiting

Overview

Base URLs

Authentication

Getting Your API Token

Using the API Token

Environment Detection

Security Best Practices

Example Implementation

Using Environment Variables

Making Authenticated Requests

Key Management

Business API Capabilities

Managing capabilities

Deployment order

Error Handling

Rate Limiting