Skip to content

Authentication (/auth/)

Create an API access token

Access to the REST API is granted via an access token. These tokens expire, so you may also have to request new tokens for long lived applications from time to time. You will receive a HTTP 401 status code if an access token has expired.

Note

For further details of the authentication scheme, see the developer guide.

REST API calls
Python API client: creating an access token

The Python API client handles creating access tokens and refreshing them for you, so not specific action is required for this API call. The following code implies creation of an access token:

from shakenfist_client import apiclient

sf_client = apiclient.Client()
curl: creating an access token 
$ curl -X POST https://shakenfist/api/auth -d '{"namespace": "system", "key": "oisoSe7T"}'
{
    "access_token": "eyJhbG...IkpXVCJ9.eyJmc...wwQ",
    "token_type": "Bearer",
    "expires_in": 900
}

This token is then used by passing it as a HTTP Authorization header with "Bearer " prepended:

$ curl -X GET https://shakenfist/api/auth/namespaces \
    -H 'Authorization: Bearer eyJhbG...IkpXVCJ9.eyJmc...wwQ' \
    -H 'Content-Type: application/json'
[
    {
        "name": "adhoc",
        "state": "created",
        "trust": {"full": ["system"]}
    }, {
        "name": "ci",
        "state": "created",
        "trust": {"full": ["system"]}
    }, {
        "name": "system",
        "state": "created",
        "trust": {"full": ["system"]}
    }
]

Namespaces

Resources in a Shaken Fist cluster are divided up into logical groupings called namespaces. All namespaces have equal permissions, except for the system namespace, which is used for administrative tasks.

Note

For a detailed reference on the state machine for namespaces, see the developer documentation on object states.

REST API calls
Python API client: list namespaces

This example lists all namespaces visible to the caller:

import json
from shakenfist_client import apiclient

sf_client = apiclient.Client()
ns = sf_client.get_namespaces()
print(json.dumps(ns, indent=4, sort_keys=True))

Which returns something like:

[
    {
        "keys": [
            "jenkins"
        ],
        "metadata": {},
        "name": "ci",
        "state": "created",
        "trust": {
            "full": [
                "system"
            ]
        },
        "version": 5
    },
    ...
]
Python API client: create a namespace

This example creates a new namespace, which is only possible if you are currently authenticated as the system namespace:

import json
from shakenfist_client import apiclient

sf_client = apiclient.Client()
ns = sf_client.create_namespace('demo')
print(json.dumps(ns, indent=4, sort_keys=True))

Which returns something like:

{
    "keys": [],
    "metadata": {},
    "name": "demo",
    "state": "created",
    "trust": {
        "full": [
            "system"
        ]
    },
    "version": 5
}
Python API client: delete a namespace

This example deletes a namespace, which is only possible if you are currently authenticated as the system namespace:

import json
from shakenfist_client import apiclient

sf_client = apiclient.Client()
ns = sf_client.delete_namespace('demo')
print(json.dumps(ns, indent=4, sort_keys=True))

The call does not return anything.

Python API client: get details of a single namespace 
import json
from shakenfist_client import apiclient

sf_client = apiclient.Client()
ns = sf_client.get_namespace('demo')
print(json.dumps(ns, indent=4, sort_keys=True))

Which returns something like:

{
    "keys": [],
    "metadata": {},
    "name": "demo",
    "state": "created",
    "trust": {
        "full": [
            "system"
        ]
    },
    "version": 5
}

Namespace keys

Callers authenticate to a namespace by providing a key to a call to /auth/ as discussed above. The calls discussed in this section relate to the management of the keys used to authenticate to a namespace.

REST API calls
Python API client: list all keys for a namespace

This example lists all the keys in a namespace:

from shakenfist_client import apiclient

sf_client = apiclient.Client()
keys = sf_client.get_namespace_keynames('ci')
print(keys)

Which returns something like:

['jenkins']
Python API client: create a new key for a namespace

This example adds a key to a namespace and then lists all keys:

from shakenfist_client import apiclient

sf_client = apiclient.Client()
sf_client.add_namespace_key('ci', 'newkey', 'thesecretvalue')

# Fetch the list of keys to make sure the new one exists
keys = sf_client.get_namespace_keynames('ci')
print(keys)

Which returns something like:

['jenkins', 'newkey']
Python API client: remove a specific key from a namespace

This example deletes a key from the namespace and then lists all keys:

from shakenfist_client import apiclient

sf_client = apiclient.Client()
sf_client.delete_namespace_key('ci', 'newkey')

# Fetch the list of keys to make sure the new one exists
keys = sf_client.get_namespace_keynames('ci')
print(keys)

Which returns something like:

['jenkins']
Python API client: update the secret portion of an existing namespace key

This example updates the secret portion of an existing namespace key to a new value:

from shakenfist_client import apiclient

sf_client = apiclient.Client()
sf_client.update_namespace_key('ci', 'newkey', 'newsecret')

Metadata

All objects exposed by the REST API may have metadata associated with them. This metadata is for storing values that are of interest to the owner of the resources, not Shaken Fist. Shaken Fist does not attempt to interpret these values at all, with the exception of the instance affinity metadata values. The metadata store is in the form of a key value store, and a general introduction is available in the user guide.

REST API calls
Python API client: set metadata on a namespace 
from shakenfist_client import apiclient

sf_client = apiclient.Client()
sf_client.set_artifact_metadata_item(img_uuid, 'foo', 'bar')
Python API client: get metadata for a namespace 
import json
from shakenfist_client import apiclient

sf_client = apiclient.Client()
md = sf_client.get_artifact_metadata(img_uuid)
print(json.dumps(md, indent=4, sort_keys=True))
Python API client: delete metadata for a namespace 
import json
from shakenfist_client import apiclient

sf_client = apiclient.Client()
sf_client.delete_artifact_metadata_item(img_uuid, 'foo')