Authentication
==============

Most API calls require authentication.  Access is controlled through OAUTH2
with JSON web tokens.

For security reasons, it is recommended that a separate user account be created
for scripting API access.  This account should have the minimum permissions
necessary to perform its duties.

API access is controlled via OAUTH2 with JSON web tokens.  In order to
authenticate, the client script first obtains an access token using a
username/password and optionally, a refresh token:

.. code:: http

    --> POST /api/mgmt.aaa/1.0/token
    {
      "user_credentials": {
          "username": "<name>",
          "password": "<password>"
      },
      "generate_refresh_token": true
    }
    <-- 201
    {
      "access_token": <access_token>,
      "refresh_token": <refresh_token>
      "expires_at": 900,
      "token_type": "bearer"
    }

All subsequent API requests must include an Authorization header containing
the access token.  Note that the "B" in "Bearer" must be capitalized:

.. code:: http

    Authorization: Bearer <access_token>

For example:

.. code:: http

    --> GET /api/npm.reports.sources/1.0/items/aggregates
    Authorization: Bearer eyJhbGciOiJIUzI1NiIs..QzWXcXNrz0ogtVhfEd2o
    <-- 200 OK
    {...}


Access tokens expire after 15 minutes.  Attempting to use an expired access
token will result in 401/Unauthorized responses.

To obtain a new token, either resubmit a username/password request, as
documented earlier, or use the refresh token instead:

.. code:: http

    --> POST /api/mgmt.aaa/1.0/token
    {
      "refresh_token": <refresh_token>
    }
    <-- 200 OK
    {
      "access_token": <access_token>,
      "expires_in": 900,
      "token_type": "bearer"
    }

Using refresh tokens is recommended, as they are more secure.  When a script
finishes, it should log out and revoke its refresh token, rendering it unusable
by a third party.  Additionally, if a refresh token is not used within 60
minutes, it will automatically be expired by the system.

A maximum of 25 refresh tokens may be active per user at once.  If a 26th token
is requested, the oldest granted token will be revoked immediately.

**Logging Out**

Logging out revokes the refresh token.  If you are not using refresh tokens,
then no special logout procedure is necessary. Access tokens are not tracked,
and will naturally expire within 15 minutes.

Revoking refresh tokens is not strictly required, but is recommended for
security. While refresh tokens will also expire automatically, they do so based
on activity and not after a fixed time.

To revoke a refresh token:

.. code:: http

    --> POST /api/mgmt.aaa/1.0/refresh_tokens/revoke
    {
      "refresh_token": <refresh_token>
    }
    <-- 200 OK