# Get started

Learn about authentication, permissions, error handling, and API key management.

## OpenAPI specification

The complete API schema is available as a single bundled file. It includes all endpoints, request and response structures, and field definitions. To integrate programmatically, download the specification in the preferred format, instead of parsing the rendered API reference:

div
a
svg
rect
text
YA
text
ML
YAML
    
a
svg
path
path
JSON
    
## Authentication and security

The Solidgate API v2 uses a simplified **Bearer token** authentication model. You no longer need to manage request signatures or multiple key sets.

br
**API key**

- **Format:** Key IDs use the prefix `akey_xxx`, secrets use the prefix `asec_xxx`.
- **Method:** Include the key in the `Authorization` header of every request.


Example header

```text
Authorization: Bearer your_secret_here
```

br
**Key flexibility**

API keys are decoupled from channels.

- **Account level:** By default, keys exist at the account level with access to all channels.
- **Channel-bound:** A key that can be restricted to one or many specific channels.


## API structure and conventions

The API follows a strict structural pattern to keep behavior predictable.

br
**Endpoint format**

All operations use the **POST** method.

```text
POST {host}/{version}/{resources}/{action}
```

- **Host:** `https://api.solidgate.com`
- **Version:** `v2`
- **Resources:** Plural form of the domain model, for example, `api-keys`, `payments`.
- **Action:** Operation name, for example, `create`, `list`, or `rotate`.


br
**Data formatting**

- **Body:** JSON
- **Property names:** `snake_case`
- **Enum values:** `UPPER_CASE`


br
## Scopes and permissions

Fine-grained access control follows the principle of least privilege. Keys can be restricted by **channel** and **permission**.

br
## API key management

Manage keys via **Solidgate Hub** or **API v2**. Hub access is available to Merchant Admin and Developer roles. Navigate to the **Developers** section and then select **API v2**.

br
**Key rotation with zero downtime**

To maintain security without service interruption, use **Rotation**.

ol
li
strong
Initiate
ul
li
strong
API:
Call 
code
/rotate
and set the rotation period in seconds
li
strong
Hub:
Click 
strong
Rotate
for the API key
li
strong
Overlap
br
During this period, both old and new secrets remain valid
      
li
strong
Expiry
br
After the period ends, the old secret is automatically deactivated
      
br
**API key operations**

All operations require an account-level API key marked in Hub as **Applies to all channels**.

| Host | Domain |
|  --- | --- |
| `POST /v2/api-keys/create` | **[Create API key](https://api.solidgate.com/v2/api-keys/create)** |
| `POST /v2/api-keys/list` | **[List API keys](https://api.solidgate.com/v2/api-keys/list)** |
| `POST /v2/api-keys/get` | **[Get API key details](https://api.solidgate.com/v2/api-keys/get)** |
| `POST /v2/api-keys/rotate` | **[Rotate API key](https://api.solidgate.com/v2/api-keys/rotate)** |


## Error handling

The API uses standard HTTP status codes. All errors return the same JSON envelope, for example:

```json
{"code": "PERMISSION_DENIED", "message": "Permission denied"}
```

Some responses include a `context` object with structured details. Every response carries a `request-id` header, share it with support when reporting issues.

| Status | Code | Description |
|  --- | --- | --- |
| `400` | `VALIDATION` | Malformed JSON or invalid field constraints. `context.constraints` lists per-field failures. |
| `401` | `UNAUTHENTICATED` | Invalid or missing API key. |
| `403` | `PERMISSION_DENIED` | Key lacks the required scope, or channel-bound key calling outside its channels. |
| `404` | `NOT_FOUND` | Resource or endpoint does not exist. |
| `422` | domain-specific | Request conflicts with current business or system state (e.g., `ENDPOINT_ALREADY_EXISTS`). |
| `429` | `RATE_LIMIT` | Quota exhausted. Check `context.next_try_at`. |
| `500` | `INTERNAL` | Server-side failure. |


## Rate limits

Rate limiting controls the frequency at which requests are made to API endpoints within specific time periods.

It helps protect against service overload while ensuring consistent performance for all clients. Exceeding limits results in a `429 Too many requests` error response.

br
**API usage limits**

Solidgate returns the `429` error response when necessary to protect legitimate merchant traffic.

Rate limits differ by endpoint based on operational and reliability needs. The Solidgate team continuously monitors system performance and may adjust these limits as needed to maintain optimal service quality.

For endpoint-specific rate limit information, visit the **Developers** section in the Solidgate Hub, which is updated as changes occur.

br
**Handle rate limits**

You can handle rate limiting by monitoring for the `429 Too many requests` error response. Effective handling combines retries and overall request flow control.

A widely used approach for handling rate limit error responses is implementing exponential backoff with jitter. This method retries requests using short initial delays that increase after each failure. Introducing randomization, or jitter, helps avoid conflicts caused by multiple clients retrying simultaneously.

While retries are useful, a significant improvement comes from regulating request flow across the entire application. The token bucket is standard practice for this purpose. It allows short bursts of requests while enforcing an average request rate over time, reducing traffic spikes and improving overall stability.

## Backward compatibility

Breaking changes can impact existing integrations and require adjustments. These are marked with a **breaking changes** badge in the changelog and include:

| Category | Change |
|  --- | --- |
| **Operation removal** | Removing an API operation. |
| **Request** | Remove or rename a field, make optional fields required, remove `oneOf`. |
| **Response** | Remove or rename a field, change HTTP status code, remove `oneOf`. |
| **Type changes** | Change request or response data types. |
| **HTTP headers** | Add required headers or remove existing ones. |
| **Enum updates** | Remove enum values. |
| **Errors** | Change existing error codes. |
| **Validation rules** | Add stricter or new rules. |
| **Authentication and authorization** | Change requirements. |


Non-breaking changes modifications do not affect existing integrations and ensure backward compatibility:

| Category | Change |
|  --- | --- |
| **Request** | Add new optional fields, change required fields to optional. |
| **Response** | Add new optional fields, change optional fields to required. |
| **HTTP headers** | Add new optional headers, change header case. |
| **Field length** | Expand maximum length. |
| **Identifier format** | Change prefixes or formatting. |
| **Webhook events** | Add new opt-in event types. |
| **Webhook schema** | Add new fields. |
| **Rate limiting** | Changes communicated at least one month in advance. |


For help, contact us.