.. vim: ft=rst

.. _requests:

========
Requests
========

A controller resource to operate on OAuth requests. This endpoint performs
OAuth signature validation to allow external services to authenticate users via
OAuth signed requests.

Valid Tokens are those obtained from the :ref:`OAuth token <token_oauth>`
resource.

Data structure
==============

* **is_valid**: boolean

If the OAuth signature provided is valid, a few extra fields are returned:

* **identifier**: identifier for the account owning the OAuth token used to sign the request
* **account_verified**: whether the account owning the OAuth token used to sign the request is verified or not

Use cases
=========

.. _requests-validate:

Validate an OAuth signature
---------------------------

.. http:post:: /api/v2/requests/validate

    Validates an OAuth-signature.

    :form http_url: the target url that was originally OAuth signed by a client
    :form http_method: the target http method that was originally OAuth signed
    :form authorization: the OAuth Authorization header resulting from OAuth signing the http request to the url ``http_url`` using method ``http_method``

    :status 200: always, with a json-encoded body returning if signature is valid or not

This method does not require authentication, and returns whether the given OAuth signature is valid for the given ``http_url`` and ``http_method``.

If the ``authorization`` field is not present, the OAuth signature is expected to be present in `http_url` as part of the query string.

Examples
........

**Request**:

.. sourcecode:: http

   POST /api/v2/requests/validate HTTP/1.1
   Host: login.ubuntu.com
   Accept: application/json
   Content-Type: application/json

   {
     "http_url": "http://example.com",
     "http_method": "GET",
     "authorization": "OAuth realm='Some client', oauth_version='1.0', oauth_signature='OitsO7PakZXODFSQsjoMQNOrkP4%3D', oauth_token='xgrsJDHzSQqFWhElJgpTvOZOCkQsLxMYVEtPZhRVteMTUHWyry', oauth_nonce='39751507', oauth_timestamp='1360097166', oauth_signature_method='HMAC-SHA1', oauth_consumer_key='64we8bn'"
   }

**Response**:

If signature is valid:

.. sourcecode:: http

   HTTP/1.1 200 OK
   Content-Type: application/json

   {
     "is_valid": true,
     "identifier": "64we8bn",
     "account_verified": true
   }

If signature is not valid:

.. sourcecode:: http

   HTTP/1.1 200 OK
   Content-Type: application/json

   {
     "is_valid": false
   }