Skip to main content
Paxos uses OAuth2 client credentials (machine-to-machine) for authentication. The SDK manages the full token lifecycle automatically — you provide your credentials once when creating the client, and every API call is authenticated transparently.

​
How It Works

When you make an API call, the SDK:
  1. Checks for a cached access token
  2. If no valid token exists, requests one from the Paxos auth server
  3. Injects the Authorization: Bearer <token> header into your request
  4. Caches the token until it expires (with a 60-second safety buffer)
  5. Refreshes the token automatically before expiry
You never need to call the token endpoint directly or manage token expiry.

​
Client Setup

client, err := paxos.NewClient(
    os.Getenv("PAXOS_CLIENT_ID"),
    os.Getenv("PAXOS_CLIENT_SECRET"),
    paxos.WithSandbox(),
)
if err != nil {
    log.Fatal(err)
}

// All calls are automatically authenticated
transfer, err := client.Transfers.GetTransfer(ctx, "txn_123")

​
Token Lifecycle

  • Tokens are cached for their full TTL (typically 1 hour) minus a 60-second buffer
  • Automatic refresh happens before expiry — no interrupted requests
  • Thread-safe: concurrent requests share a single token, and only one refresh runs at a time
  • On 401 responses, the SDK invalidates the cache, fetches a new token, and retries once

​
Credential Management

Never hardcode credentials in source code. Always use environment variables or a secret manager.
Environment variables (recommended for local development): 
export PAXOS_CLIENT_ID="your_client_id"
export PAXOS_CLIENT_SECRET="your_client_secret"
Secret managers (recommended for production): Use your infrastructure’s secret manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault) to inject credentials at runtime. The SDK accepts credentials as strings, so any secret source works.

​
Multiple Environments

Use separate clients for Sandbox and Production. Each environment has its own credentials and base URL. 
sandboxClient, _ := paxos.NewClient(
    os.Getenv("PAXOS_SANDBOX_CLIENT_ID"),
    os.Getenv("PAXOS_SANDBOX_CLIENT_SECRET"),
    paxos.WithSandbox(),
)

prodClient, _ := paxos.NewClient(
    os.Getenv("PAXOS_PROD_CLIENT_ID"),
    os.Getenv("PAXOS_PROD_CLIENT_SECRET"),
    // Production is the default
)

​
Getting API Credentials

➊ Sign in to the Paxos Dashboard (or Sandbox Dashboard) ➋ Navigate to Developer > API Credentials ➌ Create a new credential pair and select the required scopes ➍ Save the Client ID and Client Secret — the secret is only shown once
Scopes for each endpoint are listed in the Authorizations section of the API Reference.