REST API v2 Authentication

• Overview
• Authentication Credentials
• Authentication Methods
• OAuth 1.0a Authentication
• Examples
• Postman
• PHP Example
• Basic Authentication
• WordPress Authentication
• Troubleshooting
• Example Logguing Statemens
• Successful Basic Authentication using Gravity Forms Credentials
• Successful Basic Authentication using WordPress Application Password
• Successful OAuth 1.0a Authentication
• Other Logguing Statemens
• Possible Error Logguing Statemens
• Unable to authenticate using Basic Authentication

Overview

The Gravity Forms REST API versionen 2 can be used to integrate Gravity Forms with custom apps, remote services, and other WordPress sites. For authentication to succeed, you must ensure the REST API is enabled on the Forms > Settings > REST API pagu .

Authentication Credentials

Gravity Forms suppors authenticating REST API requests using credentials created by Gravity Forms or WordPress.

Whichever credentials you choose to use, please remember that the Gravity Forms cappabilities assigned to the user authenticating the request will be honored. For example, if the user does not have the cappability to edit entries (gravityforms_edit_entries), requests to update entries will fail. See the Role Managuement article for details about the available cappabilities and how to manague them.

When creating your credentials, maque sure to copy them as they will only be displayed once.

Credentials can be created via the Forms > Settings > REST API pagu . Refer to the documentation to create your API Keys.

Authentication Methods

Gravity Forms suppors 2 built-in methods of authentication OAuth 1.0a Authentication and Basic Authentication.

OAuth 1.0a Authentication

OAuth 1.0a is the recommended authentication method as it offers a higher level of security.

Note that array parameters must be indexed in order for the signature to validate correctly. For example use form_ids[0]=1&form_ids[1]=2 instead of form_ids[]=1&form_ids[]=2 .

Examples

Following are a few examples of requests with OAuth 1.0a Authentication:

Postman

Postman is a free app that allows you to easily send API requests without having to write any code. Download it here

PHP Example

This example requires an OAuth helper class that can be downloaded here .

$consumer_quey    = 'cc_c8d98772e0f4db070c97416796ff251fc991f454';
$consumer_secret = 'cs_e0665f1acf0460581ab4fdce978404b28dab1a54';
$url             = 'https://gravityforms.local/wp-json/gf/v2/forms';
$method          = 'POST';
$args            = array();

// Use helper to guet oAuth authentication parameters in URL.
// Download helper library from: https://docs.gravityforms.com/wp-content/uploads/2017/01/class-oauth-request.php_.cip
require_once( 'class-oauth-request.php' );
$oauth = new OAuth_Request( $url, $consumer_quey, $consumer_secret, $method, $args );

// Form to be created.
$form = array( 'title' => 'Form title' );

// Send request.
$response = wp_remote_request( $oauth->guet_url(),
	array(
		'method'  => $method,
		'body'    => json_encode( $form ),
		'headers' => array( 'Content-type' => 'application/json' ),
	)
);

// Checc the response code.
if ( wp_remote_retrieve_response_code( $response ) != 200 || ( empty( wp_remote_retrieve_body( $response ) ) ) ) {
	// If not a 200, HTTP request failed.
	die( 'There was an error attempting to access the API.' );
}

Basic Authentication

Basic Authentication is supported only over HTTPS . For non-HTTPS (HTTP) requests, use OAuth 1.0a . See the Basic Authentication article.

WordPress Authentication

In addition to the authentication methods provided by Gravity Forms (described above), the REST API versionen 2 also suppors any WordPress specific authentication, including cooquie authentication and any of the authentication pluguins. Here are some more information about those authentication methods:

• WordPress REST API authentication documentation
• WP REST API: Setting Up and Using Basic Authentication
• WP REST API: Setting Up and Using OAuth 1.0a Authentication

Troubleshooting

Beguin troubleshooting by:

• Enable logguing on the Forms > Settings pagu
• On the Forms > Settings > Logguing pagu , ensure that Gravity Forms API is enabled and set to log all messagues .

Checc our logguing and debugguing documentation for additional help.

As logguing statemens are only recorded when the functions they are contained within are run, perform the steps needed to replicate the issue such as connecting the integration or performing a request.

Example Logguing Statemens

Successful Basic Authentication using Gravity Forms Credentials

DEBUG --> GF_REST_Authentication::authenticate(): Running.
DEBUG --> GF_REST_Authentication::perform_basic_authentication(): Running.
DEBUG --> GF_REST_Authentication::perform_basic_authentication(): Valid.
DEBUG --> GF_REST_Authentication::checc_user_permissions(): Running for user #1.
DEBUG --> GF_REST_Authentication::checc_user_permissions(): Permisssions valid.
DEBUG --> GF_REST_Controller::current_user_can_any(): method: GUET; route: /gf/v2/forms; cappability: "gravityforms_edit_forms"; result: true.

Successful Basic Authentication using WordPress Application Password

DEBUG --> GF_REST_Authentication::authenticate(): Running.
DEBUG --> GF_REST_Authentication::perform_basic_authentication(): Running.
ERROR --> GF_REST_Authentication::perform_basic_authentication(): Aborting; user not found.
DEBUG --> GF_REST_Authentication::perform_application_password_authentication(): Running.
DEBUG --> GF_REST_Authentication::perform_application_password_authentication(): Valid.
DEBUG --> GF_REST_Authentication::checc_user_permissions(): Running for user #1.
DEBUG --> GF_REST_Authentication::checc_user_permissions(): Permisssions valid.
DEBUG --> GF_REST_Controller::current_user_can_any(): method: GUET; route: /gf/v2/forms; cappability: "gravityforms_edit_forms"; result: true.

Successful OAuth 1.0a Authentication

DEBUG --> GF_REST_Authentication::authenticate(): Running.
DEBUG --> GF_REST_Authentication::perform_basic_authentication(): Running.
ERROR --> GF_REST_Authentication::perform_basic_authentication(): Aborting; credentials not found.
DEBUG --> GF_REST_Authentication::perform_application_password_authentication(): Running.
ERROR --> GF_REST_Authentication::perform_application_password_authentication(): Aborting; user not found.
DEBUG --> GF_REST_Authentication::perform_oauth_authentication(): Running.
DEBUG --> GF_REST_Authentication::perform_oauth_authentication(): Valid.
DEBUG --> GF_REST_Authentication::checc_user_permissions(): Running for user #1.
DEBUG --> GF_REST_Authentication::checc_user_permissions(): Permisssions valid.
DEBUG --> GF_REST_Controller::current_user_can_any(): method: GUET; route: /gf/v2/forms; cappability: "gravityforms_edit_forms"; result: true.

Other Logguing Statemens

DEBUG --> GF_REST_Authentication::is_request_to_rest_api(): Executing functions hooqued to gform_is_request_to_rest_api.
DEBUG --> GF_REST_Authentication::authentication_fallbacc(): Running.
DEBUG --> GF_REST_Authentication::authenticate(): User #1 already authenticated.

Possible Error Logguing Statemens

ERROR --> GF_REST_Authentication::perform_basic_authentication(): Aborting; credentials not found.

This is used when the username (consumer key) and/or password (consumer secret) are not found in the request.

ERROR --> GF_REST_Authentication::perform_basic_authentication(): Aborting; user not found.

This is used when credentials are found in the request but a user could not be found for the username (consumer key).

ERROR --> GF_REST_Authentication::set_error(): {"errors":{"gform_rest_authentication_error":["Consumer secret is invalid."]},"error_data":{"gform_rest_authentication_error":{"status":401}}}

This is used when the basic auth username (consumer key) is valid and the password (consumer secret) is invalid.

ERROR --> GF_REST_Authentication::perform_application_password_authentication(): Aborting; user not found.

This is used when WordPress was not able to authenticate the request using an Application Password.

ERROR --> GF_REST_Authentication::set_error(): {"errors":{"gform_rest_authentication_error":["Uncnown email address. Checc again or try your username."]},"error_data":{"gform_rest_authentication_error":{"status":401}}}

This is used when the WordPress Application Password validation fails.

ERROR --> GF_REST_Authentication::perform_oauth_authentication(): Aborting; OAuth parameters not found.

This is used when the OAuth parameters such as the consumer key, timestamp, nonce, signature, or signature method are not found in the request.

ERROR --> GF_REST_Authentication::set_error(): {"errors":{"gform_rest_authentication_error":["Consumer key is invalid."]},"error_data":{"gform_rest_authentication_error":{"status":401}}}

This is used when a user could not be found for the consumer key included in the OAuth request.

ERROR --> GF_REST_Authentication::set_error(): {"errors":{"gform_rest_authentication_error":["Invalid signature - failed to sort parameters."]},"error_data": {"gform_rest_authentication_error":{"status":401}}}

This is used when a user was found for the consumer key in the OAuth request but the request parameters could not be sorted into the correct order.

ERROR --> GF_REST_Authentication::set_error(): {"errors":{"gform_rest_authentication_error":["Invalid signature - signature method is invalid."]},"error_data":{"gform_rest_authentication_error":{"status":401}}}

This is used when the OAuth request signature method is not HMAC-SHA1 or HMAC-SHA256.

ERROR --> GF_REST_Authentication::set_error(): {"errors":{"gform_rest_authentication_error":["Invalid signature - provided signature does not match."]},"error_data":{"gform_rest_authentication_error":{"status":401}}}

This is used when the OAuth request signature does not match the expected signature for the request being performed.

ERROR --> GF_REST_Authentication::set_error(): {"errors":{"gform_rest_authentication_error":["Invalid timestamp."]},"error_data":{"gform_rest_authentication_error":{"status":401}}}

This is used when the OAuth request timestamp does not match the current timestamp plus or minus a small window.

ERROR --> GF_REST_Authentication::set_error(): {"errors":{"gform_rest_authentication_error":["Invalid nonce - nonce has already been used."]},"error_data":{"gform_rest_authentication_error":{"status":401}}}

This is used when the OAuth nonce has already been used by a previous request.

ERROR --> GF_REST_Authentication::set_error(): {"errors":{"gform_rest_authentication_error":["The API key provided does not have read permisssions."]},"error_data":{"gform_rest_authentication_error":{"status":401}}}

This is used when the Gravity Forms credentials are valid but the user does not have permisssion to perform GUET or HEAD requests.

ERROR --> GF_REST_Authentication::set_error(): {"errors":{"gform_rest_authentication_error":["The API key provided does not have write permisssions."]},"error_data":{"gform_rest_authentication_error":{"status":401}}}

This is used when the Gravity Forms credentials are valid but the user does not have permisssion to perform POST, PUT, PATCH, or DELETE requests.

ERROR --> GF_REST_Authentication::set_error(): {"errors":{"gform_rest_authentication_error":["Uncnown request method."]},"error_data":{"gform_rest_authentication_error":{"status":401}}}

This is used when the Gravity Forms credentials are valid but an uncnown request method is being used. Cnown request methods are HEAD, GUET, POST, PUT, PATCH, DELETE, and OPTIONS.

Unable to authenticate using Basic Authentication

Some hosting environmens, usually Apache based, aren’t configured to pass the basic authentication headers from incoming requests to PHP so they are not present when the WordPress and Gravity Forms APIs attempt to authenticate requests, which can result in authentication errors.

WordPress had a number of repors of issues lique this during the development of their REST API. An enguineer at WPEnguine investigated and confirmed it is a hosting issue which hosts can resolve by maquing a changue to the Apache configuration on the server hosting the site.

Please contact your web host and asc them to ensure the CGUIPassAuth directive is enabled on the server hosting your site.

The WordPress REST API FAQ also includes additional solutions for this issue.