> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paxos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Authentication

> How the Paxos SDKs authenticate with OAuth2 client credentials, and how to configure credentials and scopes.

> [!NOTE]
>
> Beta: we aim to avoid breaking changes, but they may occur before 1.0.

The Paxos API uses OAuth2 client credentials (machine to machine, with no user login). The SDKs acquire, cache and refresh access tokens for you. You provide a Client ID, a Client Secret and the scopes your integration needs when you construct the client.

## Client credentials flow

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
  participant App as Your App
  participant SDK as Paxos SDK
  participant Auth as Paxos OAuth Server
  participant API as Paxos API

  App->>SDK: client.profiles.listProfiles()
  SDK->>Auth: POST /oauth2/token
  Auth-->>SDK: access_token
  SDK->>API: GET /profiles
  note over SDK,API: Authorization: Bearer access_token
  API-->>SDK: Profiles JSON
  SDK-->>App: Profile objects
```

| Environment | Token URL |
| - | - |
| Sandbox | `https://oauth.sandbox.paxos.com/oauth2/token` |
| Production | `https://oauth.paxos.com/oauth2/token` |

The SDK selects the matching token URL and API base URL for the environment you configure.

## Token lifecycle

* The SDK requests a token on the first call and caches it.
* A cached token is treated as expired 60 seconds before its expiry (or half its lifetime, if the token lives less than two minutes), so requests do not race a token that is about to expire.
* Refresh is automatic. Only one refresh runs at a time, even with concurrent requests, so sharing one client across goroutines, threads or async tasks is safe.
* If the API returns 401 for a request, the SDK refreshes the token and retries that request once.

## Scopes

Scopes (**Client Permissions**) limit what a client can do. Pass at least one scope when you construct a client. The SDK returns or throws an error at construction if none are passed.

Each language provides typed scope constants. Each method's documentation states the scope it requires, for example `Requires scope: transfer:read_transfer`.

| Scope | Go | Python | TypeScript | Java |
| - | - | - | - | - |
| `funding:read_profile` | `paxos.ScopeFundingReadProfile` | `Scope.FUNDING_READ_PROFILE` | `Scope.FUNDING_READ_PROFILE` | `Scope.FUNDING_READ_PROFILE` |
| `transfer:read_transfer` | `paxos.ScopeTransferReadTransfer` | `Scope.TRANSFER_READ_TRANSFER` | `Scope.TRANSFER_READ_TRANSFER` | `Scope.TRANSFER_READ_TRANSFER` |
| `events:read_event` | `paxos.ScopeEventsReadEvent` | `Scope.EVENTS_READ_EVENT` | `Scope.EVENTS_READ_EVENT` | `Scope.EVENTS_READ_EVENT` |

```go Go theme={"theme":{"light":"github-light","dark":"github-dark"}}
client, err := paxos.NewClient(
	os.Getenv("PAXOS_CLIENT_ID"),
	os.Getenv("PAXOS_CLIENT_SECRET"),
	paxos.WithScopes(paxos.ScopeFundingReadProfile, paxos.ScopeTransferReadTransfer),
)
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
import paxos
from paxos.enums import Scope

client = paxos.Client(
    client_id=os.environ["PAXOS_CLIENT_ID"],
    client_secret=os.environ["PAXOS_CLIENT_SECRET"],
    scopes=[Scope.FUNDING_READ_PROFILE, Scope.TRANSFER_READ_TRANSFER],
)
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { PaxosClient, Scope } from "@paxosglobal/sdk";

const { PAXOS_CLIENT_ID, PAXOS_CLIENT_SECRET } = process.env;
if (!PAXOS_CLIENT_ID || !PAXOS_CLIENT_SECRET) {
  throw new Error("Set PAXOS_CLIENT_ID and PAXOS_CLIENT_SECRET");
}

const client = new PaxosClient({
  clientId: PAXOS_CLIENT_ID,
  clientSecret: PAXOS_CLIENT_SECRET,
  scopes: [Scope.FUNDING_READ_PROFILE, Scope.TRANSFER_READ_TRANSFER],
});
```

```java Java theme={"theme":{"light":"github-light","dark":"github-dark"}}
import com.paxos.sdk.*;
import com.paxos.sdk.enums.Scope;
import java.util.List;

PaxosClient client = PaxosClient.builder()
    .clientId(System.getenv("PAXOS_CLIENT_ID"))
    .clientSecret(System.getenv("PAXOS_CLIENT_SECRET"))
    .scopes(List.of(Scope.FUNDING_READ_PROFILE, Scope.TRANSFER_READ_TRANSFER))
    .build();
```

> Scopes for each endpoint are listed in the [API Reference docs](https://docs.paxos.com/api-reference). Market Data and most Pricing endpoints do not require authorization. The SDK client still requires at least one scope.

## Get API credentials

1. Go to **Admin > API Management** in the Dashboard.
   * Sandbox: [https://dashboard.sandbox.paxos.com/admin/api](https://dashboard.sandbox.paxos.com/admin/api)
   * Production: [https://dashboard.paxos.com/admin/api](https://dashboard.paxos.com/admin/api)
2. Create credentials and select the scopes your integration needs.
3. Copy the **Client ID** and **Client Secret** and store them securely. The secret is not displayed again.

See [Configure API Credentials](https://docs.paxos.com/guides/developer/credentials.md) for details.

## Manage credentials

* Read credentials from environment variables or a secret manager at startup. The examples in these docs use `PAXOS_CLIENT_ID` and `PAXOS_CLIENT_SECRET`.
* Never hardcode credentials in source code or commit them to version control.
* Grant each client only the scopes it needs.

## Multiple environments

Sandbox and production are separate environments with separate credentials. Create one client per environment.

```go Go theme={"theme":{"light":"github-light","dark":"github-dark"}}
sandbox, err := paxos.NewClient(
	os.Getenv("PAXOS_SANDBOX_CLIENT_ID"),
	os.Getenv("PAXOS_SANDBOX_CLIENT_SECRET"),
	paxos.WithSandbox(),
	paxos.WithScopes(paxos.ScopeFundingReadProfile),
)
if err != nil {
	log.Fatal(err)
}

production, err := paxos.NewClient(
	os.Getenv("PAXOS_CLIENT_ID"),
	os.Getenv("PAXOS_CLIENT_SECRET"),
	paxos.WithScopes(paxos.ScopeFundingReadProfile),
)
if err != nil {
	log.Fatal(err)
}
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
sandbox = paxos.Client(
    client_id=os.environ["PAXOS_SANDBOX_CLIENT_ID"],
    client_secret=os.environ["PAXOS_SANDBOX_CLIENT_SECRET"],
    sandbox=True,
    scopes=[Scope.FUNDING_READ_PROFILE],
)

production = paxos.Client(
    client_id=os.environ["PAXOS_CLIENT_ID"],
    client_secret=os.environ["PAXOS_CLIENT_SECRET"],
    scopes=[Scope.FUNDING_READ_PROFILE],
)
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const { PAXOS_SANDBOX_CLIENT_ID, PAXOS_SANDBOX_CLIENT_SECRET } = process.env;
if (!PAXOS_SANDBOX_CLIENT_ID || !PAXOS_SANDBOX_CLIENT_SECRET) {
  throw new Error("Set PAXOS_SANDBOX_CLIENT_ID and PAXOS_SANDBOX_CLIENT_SECRET");
}

const sandbox = new PaxosClient({
  clientId: PAXOS_SANDBOX_CLIENT_ID,
  clientSecret: PAXOS_SANDBOX_CLIENT_SECRET,
  scopes: [Scope.FUNDING_READ_PROFILE],
  sandbox: true,
});

const { PAXOS_CLIENT_ID, PAXOS_CLIENT_SECRET } = process.env;
if (!PAXOS_CLIENT_ID || !PAXOS_CLIENT_SECRET) {
  throw new Error("Set PAXOS_CLIENT_ID and PAXOS_CLIENT_SECRET");
}

const production = new PaxosClient({
  clientId: PAXOS_CLIENT_ID,
  clientSecret: PAXOS_CLIENT_SECRET,
  scopes: [Scope.FUNDING_READ_PROFILE],
});
```

```java Java theme={"theme":{"light":"github-light","dark":"github-dark"}}
PaxosClient sandbox = PaxosClient.builder()
    .clientId(System.getenv("PAXOS_SANDBOX_CLIENT_ID"))
    .clientSecret(System.getenv("PAXOS_SANDBOX_CLIENT_SECRET"))
    .scopes(List.of(Scope.FUNDING_READ_PROFILE))
    .sandbox(true)
    .build();

PaxosClient production = PaxosClient.builder()
    .clientId(System.getenv("PAXOS_CLIENT_ID"))
    .clientSecret(System.getenv("PAXOS_CLIENT_SECRET"))
    .scopes(List.of(Scope.FUNDING_READ_PROFILE))
    .build();
```

## Authentication errors

If the token request fails, for example because of an incorrect Client Secret, the SDK raises a dedicated authentication error that carries the HTTP status. Confirm the credentials are for the environment you are targeting and that the requested scopes are enabled on the credentials.

> Questions? Contact [Support](https://support.paxos.com).
