Orders API - User Guide

The orders resource allows the user to request barbican to generate a secret. This is also very helpful for requesting the creation of public/private key pairs.

The orders resource supports the following types:

• symmetric keys

• asymmetric keys

This user guide provides high level examples of the orders resource. It will assume you will be using a local running development environment of barbican. If you need assistance with getting set up, please reference the development guide.

Creating an Order

When you want barbican to generate a secret you need to create an order. For an order to be processed correctly the parameters mode, bit_length, and algorithm must be valid. Otherwise the order will fail and the secret will not be generated. The example below shows a valid order for generating a symmetric key. You can find a more detailed explanation about the parameters in the Orders API documentation.

curl -X POST -H "X-Auth-Token: $TOKEN" -H "content-type:application/json" -d '{
"type":"key", "meta": { "name": "secretname", "algorithm": "aes",
"bit_length": 256, "mode": "cbc", "payload_content_type": "application/octet-stream"}
}' http://localhost:9311/v1/orders

You should receive an order reference after placing your order with barbican.

{"order_ref": "http://localhost:9311/v1/orders/3a5c6748-44de-4c1c-9e54-085c3f79e942"}

The order reference is used to retrieve the metadata for the order you placed which can then be used to retrieve your secret.

Retrieving an Order

In order to retrieve the order we will use the reference returned during the initial creation. (See Creating an Order.)

curl -H "X-Auth-Token: $TOKEN" -H 'Accept:application/json' \
http://localhost:9311/v1/orders/3a5c6748-44de-4c1c-9e54-085c3f79e942

The typical response is below:

{
    "created": "2015-10-15T18:15:10",
    "creator_id": "40540f978fbd45c1af18910e3e02b63f",
    "meta": {
        "algorithm": "AES",
        "bit_length": 256,
        "expiration": null,
        "mode": "cbc",
        "name": "secretname",
        "payload_content_type": "application/octet-stream"
    },
    "order_ref": "http://localhost:9311/v1/orders/3a5c6748-44de-4c1c-9e54-085c3f79e942",
    "secret_ref": "http://localhost:9311/v1/secrets/bcd1b853-edeb-4509-9f12-019b8c8dfb5f",
    "status": "ACTIVE",
    "sub_status": "Unknown",
    "sub_status_message": "Unknown",
    "type": "key",
    "updated": "2015-10-15T18:15:10"
}

This is the metadata associated with the order. To retrieve the secret generated by the order, refer to the Secrets User Guide. The order metadata is very useful for determining if your order was processed correctly. Since orders are processed asynchronously, you can use the metadata returned for the order to verify a successful secret creation. The parameters of the response are explained in more detail here.

Retrieving All Orders

It is also possible to retrieve all orders for a project.

curl -H "X-Auth-Token: $TOKEN" -H 'Accept:application/json' http://localhost:9311/v1/orders

{
    "orders": [
        {
            "created": "2015-10-15T18:15:10",
            "creator_id": "40540f978fbd45c1af18910e3e02b63f",
            "meta": {
                "algorithm": "AES",
                "bit_length": 256,
                "expiration": null,
                "mode": "cbc",
                "name": "secretname",
                "payload_content_type": "application/octet-stream"
            },
            "order_ref": "http://localhost:9311/v1/orders/3a5c6748-44de-4c1c-9e54-085c3f79e942",
            "secret_ref": "http://localhost:9311/v1/secrets/bcd1b853-edeb-4509-9f12-019b8c8dfb5f",
            "status": "ACTIVE",
            "sub_status": "Unknown",
            "sub_status_message": "Unknown",
            "type": "key",
            "updated": "2015-10-15T18:15:10"
        },
        {
            "created": "2015-10-15T18:51:35",
            "creator_id": "40540f978fbd45c1af18910e3e02b63f",
            "meta": {
                "algorithm": "AES",
                "bit_length": 256,
                "mode": "cbc",
                "expiration": null,
                "name": null
            },
            "order_ref": "http://localhost:9311/v1/orders/d99ced51-ea7a-4c14-8e11-0dda0f49c5be",
            "secret_ref": "http://localhost:9311/v1/secrets/abadd306-8235-4f6b-984a-cc48ad039def",
            "status": "ACTIVE",
            "sub_status": "Unknown",
            "sub_status_message": "Unknown",
            "type": "key",
            "updated": "2015-10-15T18:51:35"
        }
    ],
    "total": 2
}

You can refer to the orders parameters section of the Orders API documentation in order to refine your search among orders.

Deleting an Order

It is also possible to delete an order from barbican.

curl -X DELETE -H "X-Auth-Token: $TOKEN" -H 'Accept:application/json' http://localhost:9311/v1/orders/fbdd845f-4a5e-43e3-8f68-64e8f106c486

Nothing will be returned when you delete an order. If something was returned there was most likely an error while deleting the order.