> For the complete documentation index, see [llms.txt](https://tbns.gitbook.io/tbns/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tbns.gitbook.io/tbns/getting-started/quickstart.md).

# Quickstart

The TBNS API provides a RESTful interface for managing users, points, and transactions. The API supports both development (sandbox) and production environments.

### Base URL <a href="#id-0e96c414-6159-455b-bc9f-7343fdb2f7fc" id="id-0e96c414-6159-455b-bc9f-7343fdb2f7fc"></a>

```
https://api.tbns.io/functions/v1/api
```

### Environment Switching <a href="#id-6c953521-6ec6-4dd8-8721-5bde7758389d" id="id-6c953521-6ec6-4dd8-8721-5bde7758389d"></a>

#### Development/Sandbox Mode <a href="#id-66111eac-d8ea-446d-87af-94462f628ee4" id="id-66111eac-d8ea-446d-87af-94462f628ee4"></a>

Add `?dev=true` parameter to any endpoint to use the development environment:

```
curl -X GET "https://api.tbns.io/functions/v1/api/partner?dev=true" 
-H "Content-Type: application/json" 
-H "Authorization: Bearer ...."
```

You can onboard yourself to the sandbox via: <https://app.tbns.io/version-test/apply>

{% hint style="info" %}
all action on sandbox are free, pending points on production will charged from your payment asset
{% endhint %}

### Authentication <a href="#cf73cb19-7e1a-48de-8ff8-f96cf3953ec8" id="cf73cb19-7e1a-48de-8ff8-f96cf3953ec8"></a>

All API requests require two headers:

1. **Authorization Header**: static key

```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Imh3a2htcWF2enphaWVvdmtvdHdiIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NDMwMDA3NDAsImV4cCI6MjA1ODU3Njc0MH0.nKjMLLZ7cY92nchtE2mFtBCOMqb0WWbiqkekaMqVFMU
```

2. **X-Token Header**: authentication token (obtained from login)

```
X-Token: [YOUR_AUTH_TOKEN]
```

To get your authentication token, make the following request:

```
curl -X POST "https://api.tbns.io/functions/v1/api/login" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Imh3a2htcWF2enphaWVvdmtvdHdiIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NDMwMDA3NDAsImV4cCI6MjA1ODU3Njc0MH0.nKjMLLZ7cY92nchtE2mFtBCOMqb0WWbiqkekaMqVFMU" \
-d '{"email": "test@company.com", "password": "test1234"}'
```

{% hint style="info" %}
if you want to use sandbox then add dev=true to the url and use your sandbox credentials
{% endhint %}

### Creating Users

To create a new user in the system:

```
curl -X POST "https://api.tbns.io/functions/v1/api/users/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Imh3a2htcWF2enphaWVvdmtvdHdiIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NDMwMDA3NDAsImV4cCI6MjA1ODU3Njc0MH0.nKjMLLZ7cY92nchtE2mFtBCOMqb0WWbiqkekaMqVFMU" \
  -H "X-Token: X-TOKEN" \
  -d '{
    "email": "user@company.com",
    "first_name": "John",
    "last_name": "Doe"
  }'
```

{% hint style="info" %}
**Important**: Save the returned user ID for future point assignments.
{% endhint %}

### Points Management

#### Creating Points

You can create points with an initial "Open" status:

```
curl -X POST "https://api.tbns.io/functions/v1/api/points/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Imh3a2htcWF2enphaWVvdmtvdHdiIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NDMwMDA3NDAsImV4cCI6MjA1ODU3Njc0MH0.nKjMLLZ7cY92nchtE2mFtBCOMqb0WWbiqkekaMqVFMU" \
  -H "X-Token: X-TOKEN" \
  -d '{
    "subid": "order-12345",
    "amount": 100,
    "user_view_text": "Points for completing survey",
    "user_id": "1749801330826x541366778024405570"
  }'
```

#### Approving Points

To approve pending points, use the PATCH endpoint:

```
curl --location --request PATCH 'https://api.tbns.io/functions/v1/api/points/update' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Imh3a2htcWF2enphaWVvdmtvdHdiIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NDMwMDA3NDAsImV4cCI6MjA1ODU3Njc0MH0.nKjMLLZ7cY92nchtE2mFtBCOMqb0WWbiqkekaMqVFMU' \
--header 'X-Token: X-TOEKN' \
--header 'Content-Type: application/json' \
--data '{
    "point_id": "1749807859784x717369051962552600",
    "status": "Pending"
}'
```

{% hint style="info" %}
**Important Note**: Pending will automatically change to approved after the billing cycle.
{% endhint %}

### Best Practices

1. **Authentication**
   * Store authentication tokens securely
   * Implement token refresh mechanisms
   * Handle authentication errors appropriately
2. **User Management**
   * Store user IDs in your system
   * Validate user creation responses
   * Maintain proper tenant associations
3. **Points System**
   * Implement proper error handling for point creation
   * Keep track of point mint IDs
   * Consider implementing a queue system for point approval
   * Remember that pending points cannot be modified

### Integration Flow

1. Authenticate with the system
2. Create user accounts as needed
3. Generate points in "Open" status
4. Approve points when appropriate
5. Monitor point status changes