# API Documentation

Keymanager supports a JSON API to manage and query keys.

## Authentication

API access is granted only authenticated you need to supply an Authorization header with every request.

```
Authorization: Bearer <API-Key>
```

## `GET /api/json/key/:key`

Retrieves detailed information for a given key.

### Example Response

```json
{
    "key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "charge": 100,
    "expiration": "2024-03-01 00:00:00",
    "charge_orders": [
        {
            "amount": 50,
            "order_id": "111111111111",
            "expiration": "2024-03-01T00:00:00.000Z"
        },
        ...
    ]
}
```

## `POST /api/json/key/:key/discharge`

Reduces the charge of a key by specified amount.  
Can take either amount or price. If both supplied only amount is taken into account.

### Parameters

```json
{
    "amount": <AMOUNT_TO_DISCHARGE>,
    "price": <PRICE_TO_CHARGE>
}
```

### Example Response

Successfull discharge will have a response code of `201`

```json
{
    "key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "charge": 100,
    "discharged": <AMOUNT_DISCHARGED>
}
```

## `POST /api/json/key/:key/charge`

Charges a key by specified amount. Creates a Order to do so. A note can be attached to the Order.  
`manual` is currently the only valid payment processor for API.  
Can take either amount or price. If both supplied only amount is taken into account.

### Parameters

```json
{
    "amount": <AMOUNT_TO_CHARGE>,
    "price": <PRICE_TO_CHARGE>,
    "payment_processor": "manual",
    "note": <NOTE_FOR_ORDER>
}
```

### Example Response

Successfull discharge will have a response code of `201`  
If the key cannot be charged because it is already charged with too many Orders response code will be `403`

```json
{
    "key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "charge": 100,
    "charged": <AMOUNT_CHARGED>
}
```