Close [x]

OAuth-based authentication

Edit this page on GitHub

Third-party applications that integrate with Magento can use OAuth-based authentication as one of the ways to access Magento Web APIs. This authentication method uses an OAuth 1.0a handshake process.

For details about OAuth 1.0a, see The OAuth 1.0 Protocol.

To configure your third-party application (represented as an Integration in Magento) to use OAuth-based authentication to access Magento's Web APIs, read these sections:

Integration registration

As a merchant, you must register your external application as an Integration with the Magento Instance. Integration can be registered in the Magento admin (System > Extensions > Integrations) OR

You can register Integration through Magento Connect. After successful registration, Magento Connect generates a configuration file. If you choose not to register the Integration through Magento Connect, you can manually create the configuration file and make it available to merchants.

An Integration contains details like the endpoint that receives Oauth credentials and list of APIs to which access is requested.

HTTP POST with OAuth credentials

This is the preceding step before the 2-legged Oauth handshake starts. Only an administrator with access to Integration grid in the backend can initiate this.

An admin may choose to select "Save and Activate" during integration creation or click on "Activate" against a previously saved integration from the Integration grid.

This action submits the credentials to the endpoint specified when creating the Integration

The use of an HTTPS for the endpoint to pass credentials eliminates this risk to a certain extent.

HTTP POST from Magento to the Integration endpoint will contain these attributes:

  • Magento store URL. For example, http://my-magento-store.com/.
  • oauth_verifier
  • OAuth consumer key
  • OAuth consumer key secret

Integrations use the passed credentials to get a request token, which is a pre-authorized token. Integrations then use credentials plus the request token to get a long-lived access token.

2-legged Oauth Handshake

Get a request token

This is the first step in the 2-legged Oauth handshake. However, you must use these credentials to get an access token in fewer than three minutes or the credentials are disabled for security reasons. The credentials expiry can be changed from backend by the administrator. As stated previously, its defaulted to three minutes

A request token is a temporary token that the user exchanges for an access token. To get a request token from Magento:

POST /oauth/token/request

You must include these request parameters in the Authorization request header in the call:

  • oauth_consumer_key. The consumer key value that you retrieve after you register the application.
  • oauth_nonce. A random value that is uniquely generated by the application.
  • oauth_signature_method. The name of the signature method used to sign the request. Must have this value: HMAC-SHA1.
  • oauth_signature. A generated value (signature).
  • oauth_timestamp. A positive integer, expressed in the number of seconds since January 1, 1970 00:00:00 GMT.
  • oauth_version. The OAuth version.

A valid response looks like this:

oauth_token=4cqw0r7vo0s5goyyqnjb72sqj3vxwr0h&oauth_token_secret=rig3x3j5a9z5j6d4ubjwyf9f1l21itrr

Get an access token

To get an access token from Magento:

POST /oauth/token/access

You must include these request parameters in the Authorization request header in the call:

  • oauth_consumer_key. The consumer key value provided after the registration of the application.
  • oauth_nonce. A random value, uniquely generated by the application.
  • oauth_signature_method. The name of the signature method used to sign the request. Can have one of the following values: HMAC-SHA1, RSA-SHA1, or PLAINTEXT.
  • oauth_signature. A generated value (signature).
  • oauth_timestamp. A positive integer, expressed in the number of seconds since January 1, 1970 00:00:00 GMT.
  • oauth_token. The oauth_token value, or request token, obtained in Get a request token.
  • oauth_verifier. The verification code that is tied to the consumer and request token.

A valid response looks like this:

oauth_token=0lnuajnuzeei2o8xcddii5us77xnb6v0&oauth_token_secret=1c6d2hycnir5ygf39fycs6zhtaagx8pd

The response contains these fields:

  • oauth_token. The access token that provides access to protected resources.
  • oauth_token_secret. The secret that is associated with the access token.

Access the web APIs

After the Integration is authorized to make API calls, 3rd party applications (registered as Integrations in Magento) can invoke Magento web APIs by using the access token.

To use the access token to make web API calls:

GET /rest/V1/products/1234

You must include these request parameters in the Authorization request header in the call:

  • oauth_consumer_key. The customer key value provided after the registration of the application.
  • oauth_nonce. A random value, uniquely generated by the application.
  • oauth_signature_method. The name of the signature method used to sign the request. Valid values are: HMAC-SHA1, RSA-SHA1, and PLAINTEXT.
  • oauth_signature. A generated value (signature).
  • oauth_timestamp. A positive integer, expressed in the number of seconds since January 1, 1970 00:00:00 GMT.
  • oauth_token. The oauth_token, or access token, value obtained in Get an access token.

The OAuth signature

All Ouath handshake requests and Web Api requests include the signature as part of Authorization header. Its generated as follows:

You concatenate a set of URL-encoded attributes and parameters to construct the signature base string.

Use the ampersand (&) character to concatenate these attributes and parameters:

  1. HTTP method
  2. URL
  3. oauth_nonce
  4. oauth_signature_method
  5. oauth_timestamp
  6. oauth_version
  7. oauth_consumer_key
  8. oauth_token

To generate the signature, you must use the HMAC-SHA1 signature method. The signing key is the concatenated values of the consumer secret and token secret separated by the ampersand (&) character (ASCII code 38), even if empty. You must use parameter encoding to encode each value.

OAuth error codes

When the third-party application makes an invalid request to Magento, the following OAuth-related errors can occur:

HTTP code Error code Text representation Description
400 1 version_rejected The oauth_version parameter does not correspond to the "1.0" value.
400 2 parameter_absent A required parameter is missing in the request. The name of the missing parameter is specified additionally in the response.
400 3 parameter_rejected The type of the parameter or its value do not meet the protocol requirements (for example, array is passed instead of the string).
400 4 timestamp_refused The timestamp value in the oauth_timestamp parameter is incorrect.
401 5 nonce_used The nonce-timestamp combination has already been used.
400 6 signature_method_rejected The signature method is not supported. The following methods are supported: HMAC-SHA1.
401 7 signature_invalid The signature is invalid.
401 8 consumer_key_rejected The Consumer Key has incorrect length or does not exist.
401 9 token_used An attempt of authorization of an already authorized token or an attempt to exchange a not temporary token for a permanent one.
401 10 token_expired The temporary token has expired. At the moment, the mechanism of expiration of temporary tokens is not implemented and the current error is not used.
401 11 token_revoked The token is revoked by the user who authorized it.
401 12 token_rejected The token is not valid, or does not exist, or is not valid for using in the current type of request.
401 13 verifier_invalid The confirmation string does not correspond to the token.

Next step

Related topic