# **Get started with Solidgate API v2**

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

## **Authentication and security**

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

##### API key

* **Format:** Key IDs use the prefix akey_xxx, secrets use the prefix asec_xxx.
* **Method:** Key is included in the Authorization header of every request.


**Example header:**

Authorization: Bearer asec_your_private_key_here

### Key flexibility

API keys are now decoupled from channels.

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


## 

## **API structure and conventions**

To ensure predictability, the API follows a strict structural pattern.

### Endpoint format

All operations use the **POST** method.

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

* **{host}:** All endpoints share the same host https://api.solidgate.com.
* **{version}:** Use v2.
* **{resources}:** The plural form of the domain model (for example, api-keys, payments).
* **{action}:** The specific operation (for example, create, list, rotate).


### Data formatting

* **Body:** JSON format.
* **Property names:** snake_case.
* **Enum values:** UPPER_CASE.


## 

## **Scopes and permissions**

Fine-grained access control allows you to follow the principle of least privilege. You can restrict a key by **channel** and by **permission** simultaneously.

### Permission structure

Permissions are formatted as `{`domainName}:{type}.

| Type | Description |
|  --- | --- |
| **create** | Allows resource creation. |
| **read** | Allows get and list operations. |
| **manage** | Allows updates and custom domain operations. |
| **admin** | Special permission that grants full access to all resources and actions. |


* **Default state:** New keys default to admin:admin (full access).
* **Propagation:** Changes to permissions take effect within several minutes.


## 

## **Error handling** {#error-handling}

The API uses standard HTTP status codes to communicate the result of your request. All error responses follow a consistent JSON structure.

| Status | Category | Description |
|  --- | --- | --- |
| **400** | Validation | Malformed JSON or invalid field constraints. |
| **401** | Unauthenticated | Invalid or missing API key. |
| **403** | Unauthorized | API key lacks the required permissions or scopes. |
| **404** | Not found | Resource ID or endpoint does not exist. |
| **409** | Conflict | Idempotency key conflict. |
| **422** | State error | Request conflicts with the current system state (for example, duplicate subscription). |
| **429** | Rate limit | Request quota exhausted. Check next_try_at in context. |
| **500** | Internal | Server-side failure. |


## 

## **API key management**

You can manage your keys via **Solidgate Hub** or via **API v2** itself. Hub access is available only to the Merchant admin and Developer roles. Navigate to the **Developers** section, and there select the **v2** subsection.

### Key rotation with zero-downtime

To maintain security without interrupting service, use the **Rotation** feature.

1. **Initiate**
  * **via API**: Call the /rotate endpoint and specify a rotation period in seconds.
  * **via Hub**: Press the **Rotate** button for an API key.
2. **Overlap**
During this period, **both** the old and new secrets are accepted.
3. **Expiry**
Once the period ends, the old secret is automatically deactivated.


### API key operations

Use these endpoints to manage your API keys via the Solidgate API v2. All operations require an account-level API key, indicated in Hub as **Applies to all channels**.

* **Create API key:** POST /v2/api-keys/create
* **List API keys:** POST /v2/api-keys/list
* **Get API key details:** POST /v2/api-keys/get
* **Rotate API key:** POST /v2/api-keys/rotate