Tokens
======

Create token (authenticate)
---------------------------

In order to generate a token, you must pass in the JSON template that is
sent to the API. This is because Rackspace's operation expects a
slightly different entity body than OpenStack Keystone.

To do this, and then generate a token:

.. code-block:: php

  $json = $client->getCredentials();

  /** @var $response Guzzle\Http\Message\Response */
  $response = $service->generateToken($json);
  $jsonBody = $response->json();

When a token is generated by the API, there are a few things returned:

* a `service catalog <http://docs.rackspace.com/auth/api/v2.0/auth-client-devguide/content/Svc_Catalog_ovw.html>`_
  outlining all of the services you can interact with,
  including their names, service types, and endpoint URLs. Which services
  make up your catalog, and how your catalog is structured, will depend on
  your service provider.

* details about your token, such as its ID, created and expiration date

* details about your user account

* details about your tenant

Interacting with the service catalog
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Once you have the ``$jsonBody``, you can construct a ``Catalog`` object for
easier interaction:

.. code-block:: php

  $data = $jsonBody->access->serviceCatalog;
  $catalog = OpenCloud\Common\Service\Catalog::factory($data);

  foreach ($catalog->getItems() as $service) {
    /** @param $service OpenCloud\Common\Service\CatalogItem */
    printf("Catalog item: Name [%s] Type [%s]\n", $service->getName(), $service->getType());

    foreach ($service->getEndpoints() as $endpoint) {
      printf("  Endpoint provided: Region [%s] PublicURL [%s] PrivateURL [%s]\n",
        $endpoint->getRegion(), $endpoint->getPublicUrl(), $endpoint->getPrivateUrl());
    }
  }

Interacting with tokens
~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: php

  $data = $jsonBody->access->token;
  $token = $service->resource('Token', $data);

  printf("Token ID: %s - Token expiry %s", $token->getId(), $token->getExpires());

  if ($token->hasExpired()) {
    // ...
  }

Interacting with users
~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: php

  $data = $jsonBody->access->user;
  $user = $service->resource('User', $data);

To see which methods you can call on ``$user`` (which implements
``OpenCloud\Identity\Resource\User``), see our :doc:`user documentation <users>`
which accompanies this guide.


Interacting with tenants
~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: php

  $data = $jsonBody->access->tenant;
  $tenant = $service->resource('Tenant', $data);

To see which methods you can call on ``$tenant`` (which implements
``OpenCloud\Identity\Resource\Tenant``), see our :doc:`user documentation <tenant>`
which accompanies this guide.


Revoke token (destroy session)
------------------------------

.. code-block:: php

  $service->revokeToken('{tokenId}');
