# 🔐 Authentication

Making secured API requests.

Tyms API uses a simple yet secure authentication model based on **secret API keys**. Every API request must include your API key in the `Authorization` header to verify that the request is coming from a trusted and authorized source.

Think of your API key as a **password for your integration**, keep it secure and never expose it publicly (e.g., in client-side code or public repositories).

***

### 🔑 Getting Your API Key

You can retrieve your API keys from the [Tyms Dashboard](https://app.tyms.io/). Each Tyms business account comes with:

- **A Production API Key** : for live, real-time financial data
- **A Sandbox API Key** : for safe development and testing, without any impact on production data

Use the appropriate key based on your environment to avoid unintended changes to live business records.

***

### 🌍 API Environments

Tyms provides two separate environments for different stages of your integration:

| Environment    | Purpose                                                       | Base URL                            |
| -------------- | ------------------------------------------------------------- | ----------------------------------- |
| **Sandbox**    | Develop and test safely without affecting real business data. | `https://staging-api.tymsbook.com/` |
| **Production** | Access and manage real business data in a live environment.   | `https://api.tyms.io/`              |

If you need access to a sandbox account, email us at:  
📧 **[developer@tyms.io](mailto:developer@tyms.io)**  
**Subject:** `Request for test account for development`

***

### 🧾 Making API Requests

Tyms accepts standard RESTful requests using `POST`, `GET`, `PUT`, and `DELETE` methods over **HTTPS**.

Every request must meet these basic requirements:

- Include your secret API key in the `Authorization` header:

  ```
  Authorization: Bearer <your-secret-api-key>
  ```
- Format the request body as **valid JSON**
- Use the correct **base URL** depending on the environment

***

### 📬 Sample Response Format

Tyms responds to API calls with standard HTTP status codes and well-structured JSON payloads. A successful response typically looks like this:

```json
{
  "status": "success",
  "message": "Authorization request initiated successfully",
  "data": "https://tymsbook-web.web.app/auth?client_id=tyms_pub_e7cad0bd-3d11-4646-8b02-b62441c9c204?redirect_url=https://tymsbook-web.web.app/dashboard/home?code=192303"
}
```

***

### 📦 Pagination

For endpoints that return multiple results (e.g., `GET /sales`), responses are **paginated** to optimize performance and usability.

Use the following query parameters:

- `limit` — The number of records per page (default: 10)
- `page` — The page number to retrieve

**Example:**

```
GET /sales?limit=20&page=2
```

***

### ✅ Quick Tips

- Never expose your secret key in front-end applications.
- Use sandbox keys during development and switch to production keys when ready to go live.
- Monitor usage and set alerts to avoid hitting rate limits.
- Handle `401 Unauthorized` and `429 Too Many Requests` responses gracefully in your integration.