API Documentation

Ignacio Burgueño edited this page Sep 25, 2013 · 7 revisions
Clone this wiki locally

API Documentation

This document describes the API of the OAuth module.

new

Builds a new OAuth client instance.

OAuth:new(consumer_key, consumer_secret, endpoints, [params])

It takes the following parameters:

  • consumer_key is the public key
  • consumer_secret is the private key
  • endpoints is a table containing the URLs where the Service Provider exposes its endpoints. Each endpoint is either a string (its url, the method is POST by default) or a table, with the url in the array part and the method in the 'method' field.
  • params is an optional table with additional parameters:
    • field SignatureMethod indicates the signature method used by the server (PLAINTEXT, RSA-SHA1, HMAC-SHA1 (default) )
    • field UseAuthHeaders indicates if the server supports oauth_xxx parameters to be sent in the 'Authorization' HTTP header (true by default)

The following methods are meant to be called on a OAuth client instance, like this: client:RequestToken().

RequestToken

Requests temporary credentials.

client:RequestToken([arguments, [headers] ])

It takes the following parameters:

  • arguments is an optional table with whose keys and values will be encoded as "application/x-www-form-urlencoded" (when doing a POST) or encoded and sent in the query string (when doing a GET).
  • headers is an optional table with http headers to be sent in the request

Returns a table containing the returned values from the server if succesfull or throws an error otherwise.

BuildAuthorizationUrl

Builds the authorization url that the resource owner must navigate to to grant permission to the client as specified in Resource Owner Authorization

client:BuildAuthorizationUrl([arguments])

  • arguments is an optional table whose keys and values will be encoded and sent in the query string.

Returns the fully constructed URL, with oauth_token and custom parameters encoded.

GetAccessToken

Exchanges a request token for an Access token as described here

client:GetAccessToken([arguments[, headers] ])

  • arguments is an optional table with whose keys and values will be encoded as "application/x-www-form-urlencoded" (when doing a POST) or encoded and sent in the query string (when doing a GET).
  • headers is an optional table with http headers to be sent in the request

Returns a table containing the returned values from the server if succesfull or nil plus the http status code (a number), a table with the response headers, the status line and the response itself.

PerformRequest

After retrieving an access token, this method is used to issue properly authenticated requests.

client:PerformRequest(method, url, [arguments[, headers] ])

  • method is the http method (GET, POST, etc)
  • url is the url to request
  • arguments is an optional table with whose keys and values will be encoded as "application/x-www-form-urlencoded" (when doing a POST) or encoded and sent in the query string (when doing a GET).
  • arguments is an optional table whose keys and values will be encoded as "application/x-www-form-urlencoded" (when doing a POST) or encoded and sent in the query string (when doing a GET). It can also be a string with the body to be sent in the request (usually a POST). In that case, you need to supply a valid Content-Type header.
  • headers is an optional table with http headers to be sent in the request

Returns the http status code (a number), a table with the response headers, the status line and the response body itself.

BuildRequest

After retrieving an access token, this method is used to build properly authenticated requests but it won't send it. Instead, it will return the needed headers and data that needs to be sent.

client:BuildRequest(method, url, [arguments[, headers] ])

  • method is the http method (GET, POST, etc)
  • url is the url to request
  • arguments is an optional table whose keys and values will be encoded as "application/x-www-form-urlencoded" (when doing a POST) or encoded and sent in the query string (when doing a GET). It can also be a string with the body to be sent in the request (usually a POST). In that case, you need to supply a valid Content-Type header.
  • headers is an optional table with http headers to be sent in the request

Returns a table with headers, a table with the (cleaned up) arguments and the request body. So, now you can send the data with whatever network library you have at hand.

Set/GetToken

Sets or gets the oauth_token OAuth header on a client instance.

old_value = client:GetToken()
client:SetToken(value)

Set/GetTokenSecret

Sets or gets the oauth_token_secret OAuth header on a client instance.

old_value = client:GetTokenSecret()
client:SetTokenSecret(value)

Set/GetVerifier

Sets or gets the oauth_verifier OAuth header on a client instance.

old_value = client:GetVerifier()
client:SetVerifier(value)