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

# Authentication

> Learn how to authenticate with the TRXN API using bearer tokens, handle two-factor authentication, and manage sandbox environments.

TRXN uses token-based authentication for all API requests. Every API call (except authentication itself) requires a valid API token.

## Overview

| Aspect                    | Details                                    |
| ------------------------- | ------------------------------------------ |
| **Authentication method** | Bearer token                               |
| **Header**                | `Authorization: Bearer YOUR_TOKEN`         |
| **Token format**          | 32-character hex string                    |
| **Account scoping**       | Each token is tied to one account          |
| **Sandbox support**       | Tokens can be scoped to a specific sandbox |

## Obtaining an API token

### Option 1: Via the dashboard (recommended)

1. Navigate to **API Tokens** in the account settings.
2. Click **New API Token**.
3. Enter a name for the token.
4. The token value is displayed once after creation -- copy it immediately.

<Warning>
  The token value is only displayed once at creation time. If you lose it, you will need to create a new token.
</Warning>

### Option 2: Via the auth endpoint

Exchange email and password credentials for an API token programmatically.

```
POST /v1/auth
```

<ParamField body="email" type="string" required>
  The user's email address.
</ParamField>

<ParamField body="password" type="string" required>
  The user's password.
</ParamField>

<ParamField body="otp_attempt" type="string">
  The six-digit one-time password from the user's authenticator app. Required when the user has two-factor authentication enabled.
</ParamField>

#### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.gettrxn.com/v1/auth \
    -H "Content-Type: application/json" \
    -d '{
      "email": "user@example.com",
      "password": "your_password"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.gettrxn.com/v1/auth",
      json={
          "email": "user@example.com",
          "password": "your_password"
      }
  )
  data = response.json()
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.gettrxn.com/v1/auth", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      email: "user@example.com",
      password: "your_password"
    })
  });
  const data = await response.json();
  ```
</CodeGroup>

#### Success response (200 OK)

```json theme={null}
{
  "token": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
```

#### Error responses

**Invalid credentials (401 Unauthorized):**

```json theme={null}
{
  "error": "Invalid Email or password."
}
```

**Two-factor authentication required (422 Unprocessable Entity):**

```json theme={null}
{
  "error": "otp_attempt_required"
}
```

When the user has two-factor authentication enabled, include the `otp_attempt` parameter:

```bash theme={null}
curl -X POST https://api.gettrxn.com/v1/auth \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password",
    "otp_attempt": "123456"
  }'
```

**Invalid OTP code (401 Unauthorized):**

```json theme={null}
{
  "error": "Incorrect verification code"
}
```

## Authenticating API requests

Include the token in the `Authorization` header of every API request:

```bash theme={null}
curl https://api.gettrxn.com/v1/customers \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Authentication header format

```
Authorization: Bearer YOUR_TOKEN
```

The API also accepts the `token` keyword:

```
Authorization: token YOUR_TOKEN
```

### Missing or invalid token (401 Unauthorized)

Requests without a valid token receive an empty `401 Unauthorized` response:

```
HTTP/1.1 401 Unauthorized
```

No JSON body is returned for missing or invalid tokens.

## Account scoping

Each API token is tied to a specific account. All API requests are automatically scoped to that account's data:

* **Customers** returned are only those belonging to the token's account.
* **Invoices**, **products**, **prices**, and other resources are similarly scoped.
* Tokens cannot access data from other accounts.

### Token usage tracking

Each time a token is used for authentication, its `last_used_at` timestamp is updated. This is visible in the dashboard for auditing purposes.

## Sandbox mode

API tokens can be created within a sandbox environment for testing purposes.

<Note>
  Production tokens access only production data. Sandbox tokens access only sandbox data. The sandbox association is set when the token is created.
</Note>

### How it works

* **Production tokens** (no sandbox) access only production data.
* **Sandbox tokens** access only sandbox data.
* The sandbox association is set when the token is created.

### Creating a sandbox token

Create an API token while in sandbox mode through the dashboard. The token will automatically be scoped to that sandbox and will only return sandbox data.

## Token management

### Listing tokens

View all API tokens for an account in the dashboard at **API Tokens**.

### Revoking a token

Delete an API token from the dashboard to immediately revoke access. Any requests using that token will receive a `401 Unauthorized` response.

## Code examples

<CodeGroup>
  ```ruby Ruby theme={null}
  require "net/http"
  require "json"

  uri = URI("https://api.gettrxn.com/v1/customers")
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Get.new(uri)
  request["Authorization"] = "Bearer YOUR_TOKEN"

  response = http.request(request)
  data = JSON.parse(response.body)
  ```

  ```python Python theme={null}
  import requests

  headers = {
      "Authorization": "Bearer YOUR_TOKEN"
  }

  response = requests.get(
      "https://api.gettrxn.com/v1/customers",
      headers=headers
  )
  data = response.json()
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.gettrxn.com/v1/customers", {
    headers: {
      "Authorization": "Bearer YOUR_TOKEN"
    }
  });
  const data = await response.json();
  ```

  ```bash cURL theme={null}
  # List customers
  curl https://api.gettrxn.com/v1/customers \
    -H "Authorization: Bearer YOUR_TOKEN"

  # Create a customer
  curl -X POST https://api.gettrxn.com/v1/customers \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"email": "customer@example.com", "first_name": "Jane", "last_name": "Doe"}'
  ```
</CodeGroup>

## Available API endpoints

All endpoints require authentication unless noted otherwise.

| Endpoint                                  | Methods           | Description                         |
| ----------------------------------------- | ----------------- | ----------------------------------- |
| `/v1/auth`                                | POST              | Obtain API token (no auth required) |
| `/v1/me`                                  | GET               | Current user info                   |
| `/v1/accounts`                            | CRUD              | Account management                  |
| `/v1/customers`                           | CRUD              | Customer management                 |
| `/v1/products`                            | CRUD              | Product management                  |
| `/v1/prices`                              | CRUD              | Price management                    |
| `/v1/invoices`                            | CRUD              | Invoice management                  |
| `/v1/subscriptions`                       | CRUD              | Subscription management             |
| `/v1/webhook_endpoints`                   | CRUD              | Webhook endpoint management         |
| `/v1/crypto_transactions`                 | GET, POST         | Crypto transaction records          |
| `/v1/crypto_addresses`                    | GET, POST, DELETE | Crypto address management           |
| `/v1/crypto_payment_claims`               | GET               | Payment claim records               |
| `/v1/crypto_payment_claims/:id/approval`  | POST              | Approve a claim                     |
| `/v1/crypto_payment_claims/:id/rejection` | POST              | Reject a claim                      |
| `/v1/wallets`                             | GET               | Wallet information                  |
| `/v1/payment_claim_links`                 | GET, POST, DELETE | Payment claim links                 |

## Best practices

<Tip>
  Follow these guidelines to keep your API tokens secure and your integration reliable.
</Tip>

1. **Store tokens securely** -- never commit tokens to source control or expose them in client-side code.
2. **Use environment variables** to store tokens in your application.
3. **Create separate tokens** for different integrations or environments.
4. **Revoke unused tokens** promptly when they are no longer needed.
5. **Use sandbox tokens** for development and testing to avoid affecting production data.
6. **Monitor usage** by checking `last_used_at` in the dashboard for unusual activity.