# Quick Start: Authorization and API Basics

Welcome to the SimPay API documentation! Before you move on to integrating specific services (Online Payments, DirectBilling, or SMS), you need to learn the basic principles of communication with our servers.

Our API is designed with REST architecture, and data exchange is done exclusively in **JSON** format.

## 1. Obtaining and Sending the API Key

Access to the API is protected. To send requests to us, you need a unique access key (Bearer Token).

1. Log in to the **SimPay Client Panel**.
2. Go to the **My Account > API Keys** tab.
3. Generate a new key and copy its value.


The generated token must be included with **every** request sent to our API using the `Authorization` header. Also remember to include the appropriate headers specifying the data format.

**Example HTTP request skeleton:**


```http
POST /api/endpoint HTTP/1.1
Host: api.simpay.pl
Authorization: Bearer YOUR_API_KEY
Accept: application/json
Content-Type: application/json
```

## 2. API Key Security

Your API key is the virtual equivalent of your company keys – it grants access to generating transactions and even initiating refunds. Treat it with the utmost care.

Important Security Rules
* **Never expose the API key on the client side (Frontend).** The key must not appear in JavaScript code (React, Vue, Angular) or in mobile applications. Communication with SimPay must always be done from your server (Backend).
* **Do not commit the key to a code repository.** Use environment variables (e.g., `.env` files) that are ignored by version control systems (Git).


## 3. Rate Limiting and Key Permissions

SimPay offers powerful access granulation tools that help minimize risk in case of a key leak. We strongly recommend using them when generating tokens in the Client Panel:

### Permissions (Abilities)

Instead of creating a single key for everything ("God Mode"), create keys dedicated to specific tasks. If a key is only meant for generating new online payments on your store's website, uncheck its permissions for handling refunds or viewing transaction history.

### IP Address Restrictions (Whitelist)

This is the strongest security measure. In the key settings, you can define the exact IP addresses of your servers. If someone steals your API key and tries to use it from a different computer, our API will immediately reject such a request (error 403).

## 4. Error Codes (HTTP Status Codes)

Our API uses standard HTTP status codes to inform you about the result of an operation. Codes in the `2xx` group indicate success, while `4xx` indicate an error on your request's side.

Every error response contains a JSON object with an `errorCode` field to facilitate debugging. In case of validation errors (422), we additionally return an `errors` object with a list of invalid fields.

| HTTP Code | Error Type | Description | Example `errorCode` |
|  --- | --- | --- | --- |
| **`200 OK`** | Success | The request was processed successfully. | - |
| **`401 Unauthorized`** | No authorization | No API token was provided in the header, or it is invalid/expired. | `UNAUTHORIZED` |
| **`403 Forbidden`** | Access denied | Your token does not have the appropriate permissions (Abilities) to perform this action, or the request came from an IP address not on the whitelist. | `INVALID_ABILITY_PROVIDED`, `IP_ADDRESS_NOT_WHITELISTED` |
| **`404 Not Found`** | Not found | You are trying to query a non-existent endpoint, or an incorrect service/transaction ID was provided in the URL. | `ROUTE_NOT_FOUND`, `SERVICE_NOT_FOUND`, `TRANSACTION_NOT_FOUND` |
| **`422 Unprocessable Entity`** | Validation error | The submitted data is incomplete or has an incorrect format (e.g., missing required `amount` or invalid currency). | `VALIDATION_ERROR` |


**Example response for error 422 (VALIDATION_ERROR):**


```json
{
  "success": false,
  "errorCode": "VALIDATION_ERROR",
  "errors": {
    "amount": [
      "The amount field is required."
    ],
    "currency": [
      "The selected currency is invalid."
    ]
  }
}
```

## What's Next?

You now know the communication rules and how to properly authorize your requests. Time to start generating real transactions!

Choose the module you want to integrate with:

* 👉 **[Online Payments (Transfers, BLIK, Cards)](/payment)**
* 👉 **[IPN Notification Handling](/notifications/payment)**
* 👉 **[DirectBilling Payments (DCB)](/directbilling)**
* 👉 **[SMS Premium Payments](/sms)**