OAuth Supporting Methods

OAuth allows you to share private resources stored on one site with another site without having to furnish your username and password. The OAuth 2.0 specification (draft) defines several ways of obtaining an access token, which is used by the client application to access resources on behalf of the end-user. Several of these flows require that service providers (or their authorization servers) respond to client calls directly. In order to support this requirement, Mashery provides an API that service providers can use in order to implement these flows. See http://tools.ietf.org/html/draft-ietf-oauth-v2-16.

The goal of this API is to simplify the provider's OAuth 2.0 implementation while allowing for maximum flexibility. In most cases, the provider passes the arguments as they are received from the client. Mashery then:

  1. Detects the OAuth 2.0 flow based on the supplied arguments
  2. Validates that the flow is supported by the related service definition
  3. Validates all arguments with respect to the flow

In some cases, the provider needs to extract some of the arguments in a protocol-specific manner. For instance, client credentials might be supplied by the client in the form of HTTP Basic Authentication (i.e., the Authorization header).

Underlying Protocol

Mashery API uses JSON-RPC as the underlying API protocol. See http://support.mashery.com/docs/read/mashery_api/20/JSON_RPC.

Types

Client Object

Parameters

Parameter Type Description
client_id string The API key of the developer whose application is requesting access
client_secret string Client credentials if supplied with request

URI Object

Parameters

Parameter Type Description
redirect_uri string URI to redirect to after issuing authorization code. Used to verify subsequent access token request.
state string Optional application defined value used to maintain state between request and callback.

Token_Data Object

Parameters

Parameter Type Description
grant_type string

Optional, one of the following options:

  • "authorization_code" (for Authorization Code flow)
  • "implicit" (for Implicit Grant flow)
  • "password" (for Resource Owner Password Credentials flow)
  • "client_credentials" (for Client Credentials flow)
  • "refresh_token" (when using refresh token to obtain a new access token)
  • or a supported extension
scope string Optional space-delimited list of scope identifiers (provider-defined)
code string Optional authorization code previously obtained by calling createAuthorizationCode (required when grant_type is "authorization_code")
response_type string Optional one of "code" or "token"
refresh_token string Optional refresh token obtained with a previously issued access token (required when grant_type is "refresh_token")
access_token string Optional, identifies the token data

OAuth Error Object

Parameters

Parameter Type Description
error integer

OAuth specific error code. Used when returning errors back to calling application.

error_descrption string Optional human readable error message.
error_response null or array

Indicates if error message is to be returned to calling application or handled strictly by Mashery API consumer.

  • null value indicates error message is for Mashery API consumer to handle and not to be returned directly to caller.
  • non-null array structure:
    • redirect: boolean; indicates if response parameter contains a redirect url or response body
    • response: string; either the redirect url to send the caller to or the message body of the response to return to the caller
    • type: null or string; contains content-type of included response if not a redirect url

See OAuth Generated Errors for more on OAuth errors.

Docs Navigation