.. meta::
    :description: This documentation will guide you through the use of the Memset API.

.. index::
   double: Methods; apikey

.. _apikey:

API Key Methods
---------------

API for API keys
================

The API keys are for accessing the Memset API programatically not
using a username and password.  Their scope can be limited on creation
so that it is possible to create API keys with just a single purpose.

Scopes
------

API keys can be scoped with "name", "method" or with both.

API keys created with "name" scopes can only be called with a
parameter called "name" with one of the values supplied in the scope
when it was created.

API keys created with "method" scopes can only be used to call those
named methods and no others.

For example if an API key was created with the scopes::

   {
       "name": [ "server1", "server2" ]
   }

Then it could only be used to access methods which take a "name"
parameter and with that set to either "server1" or "server2"

If an API key was created with the scopes::

   {
       "method": [ "server.reboot" ]
   }

Then it could only be used to call the "server.reboot" method.

If an API key was created with the scopes::

   {
       "method": [ "server.reboot" ],
       "name": [ "server1", "server2" ]
   }

Then it could only be used to call the "server.reboot" method on
"server1" or "server2".

.. function:: apikey.add_scope

    Adds a single scope to an API key
    
    :param id: The API key. API Keys are 32 hex digits.
    :type id: String
    
    :param scope_name: The name of the API scope. Acceptable values: 'method', 'name'.
    :type scope_name: String
    
    :param value: The value of the API scope. Ensure this value has at most 50 characters.
    :type value: String
    
    :returns: Dictionary: as described in :func:`apikey.info`.

.. function:: apikey.create

    Creates a new API key for this account.
    
    :param scopes: The scopes dictionary as described in :func:`apikey.info`.
    :type scopes: Dictionary, Optional
    
    :param comment: User comment. Ensure this value has at most 255 characters.
    :type comment: String, Optional
    
    :returns: a dictionary containing the new api key as described in :func:`apikey.info`.

.. function:: apikey.delete

    Deletes an API key.
    
    :param id: The API key. API Keys are 32 hex digits.
    :type id: String
    
    :returns: an empty dictionary.

.. function:: apikey.delete_scope

    Deletes a single scope to an API key.  Doesn't raise an error if
    it didn't exist.
    
    :param id: The API key. API Keys are 32 hex digits.
    :type id: String
    
    :param scope_name: The name of the API scope. Acceptable values: 'method', 'name'.
    :type scope_name: String
    
    :param value: The value of the API scope. Ensure this value has at most 50 characters.
    :type value: String
    
    :returns: Dictionary: as described in :func:`apikey.info`.

.. function:: apikey.info

    Describes the API key.
    
    :param id: The API key. API Keys are 32 hex digits.
    :type id: String
    
    :returns: a dictionary with the following keys:
    
        **key**
            String: 32 digit hex which is the api_key.
        **scopes**
            Dictionary: A dictionary of Lists of String.  The keys are
            the scope names ("method" or "name") and the values are
            lists of valid entries for those scopes
        **comment**
            String: User comment associated to the key (if any).
        **created**
            Date: Date when the key was created.

.. function:: apikey.list

    List all the API keys for this account.
    
    
    :returns: a list of dictionaries where each dictionary is as
        described in :func:`apikey.info`.