Tokens
======

Tokens are used to authenticate and authorize your interactions with OpenStack APIs. Tokens come in many scopes,
representing various authorization and sources of identity.

.. osdoc:: https://docs.openstack.org/keystone/latest/admin/tokens-overview.html

Generate token
--------------

Token is generated when you create the ``OpenStack`` object. You can also generate another token using the following methods.

Generate token with user ID
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. sample:: Identity/v3/tokens/generate_token_with_user_id.php

Generate token with username
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Since usernames will not be unique across an entire OpenStack installation, when authenticating with them,
you must also provide your domain ID. You do not have to do this if you authenticate with a user ID.

.. sample:: Identity/v3/tokens/generate_token_with_username.php

Generate token with application credential ID
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. sample:: Identity/v3/tokens/generate_token_with_application_credential_id.php


Generate token from ID
~~~~~~~~~~~~~~~~~~~~~~

.. sample:: Identity/v3/tokens/generate_token_from_id.php

Generate token scoped to project ID
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. sample:: Identity/v3/tokens/generate_token_scoped_to_project_id.php

Generate token scoped to project name
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Since project names will not be unique across an entire OpenStack installation, when authenticating with them you must
also provide your domain ID. You do not have to do this if you authenticate with a project ID.

.. sample:: Identity/v3/tokens/generate_token_scoped_to_project_name.php

Validate token
--------------

.. sample:: Identity/v3/tokens/validate_token.php

Revoke token
------------

.. sample:: Identity/v3/tokens/revoke_token.php

Cache authentication token
--------------------------

Use case
~~~~~~~~

Before the SDK performs an API call, it will first authenticate to the OpenStack Identity service using the provided
credentials.

If the user's credential is valid, credentials are valid, the Identity service returns an authentication token. The SDK
will then use this authentication token and service catalog in all subsequent API calls.

This setup typically works well for CLI applications. However, for web-based applications, performance
is undesirable since authentication step adds ~100ms to the response time.

In order to improve performance, the SDK allows users to export and store authentication tokens, and re-use until they
expire.


Generate token and persist to file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. sample:: Identity/v3/tokens/export_authentication_token.php
    :full:


For scalability, it is recommended that cached tokens are stored in persistent storage such as memcache or redis instead
of a local file.

Initialize Open Stack using cached authentication token
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. sample:: Identity/v3/tokens/use_cached_authentication_token.php
    :full: