availability

OAuth is in closed beta in production, and open beta in sandbox. To express interest in the production beta release, contact our Business Development team.

Once you've configured your OAuth application, the first step in the OAuth sequence is to generate a connect URL. The connect URL goes to a Braintree website that prompts the merchant to log into their Braintree account and agree the OAuth scopes you're requesting.

To generate the connect URL, you'll need to:

  1. Provide your OAuth application credentials from the Braintree Control Panel
  2. Specify parameters for the connect URL:
    • redirect_uri (required)
    • scope (required)
    • state
Ruby
Copy
Copied
gateway = Braintree::Gateway.new(
  :client_id => "use_your_client_id",
  :client_secret => "use_your_client_secret",
)

url = gateway.oauth.connect_url(
  :redirect_uri => "https://your.redirect.uri",
  :scope => "shared_vault_transactions",
  :state => "foo_state"
)

Access your OAuth application credentials

  1. Log into either the production Control Panel or the sandbox Control Panel, depending on which environment you are working in
  2. Navigate to Settings > OAuth Applications
  3. Click reveal under the desired OAuth application to open a modal with the client_id and client_secret

Specify connect URL parameters

Redirect URI

The redirect_uri parameter specifies where Braintree should send the merchant after they authorize your application. All redirect URIs must be whitelisted as part of your OAuth configuration.

note

Please use a full URI, including the protocol (http or https). In production, https is required.

Scope

The scope parameter indicates the permissions you're requesting for the merchant's account. For example, the code snippet above shows the shared_vault_transactions scope, which allows Shared Vault transaction API calls.

If you would like to request multiple scopes, use a comma delimited string, e.g. grant_payment_method,shared_vault_transactions. See the full list of available scopes on the OAuth Reference page.

State

The state parameter is part of the OAuth 2.0 specification and is used to prevent Cross Site Request Forgery (CSRF) attacks. Braintree will always return the submitted state verbatim when redirecting back to the redirect URI. You can verify the authenticity of the request to the redirect URI by submitting a non-guessable state parameter when generating the connect URL and ensuring the value returned matches the value submitted.

Be sure that the contents of the state parameter are properly escaped (typically via base 64 or URL encoding) to prevent them from being altered by a merchant's browser when redirecting at the end of the OAuth flow.

Next Page: Client-side Connect Flow →

Still have questions?

If you can’t find an answer, contact our Support team