OAuth

Connect URLsanchor

availability

OAuth is in closed beta in production, and open beta in sandbox. Contact us to express interest in the production beta release.

Once you've configured your OAuth application, the first step in the [OAuth sequence] (/braintree/docs/guides/extend/oauth/overview#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
  1. Ruby
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 credentialsanchor

  1. Log into either the production Control Panel or the sandbox Control Panel, depending on which environment you are working in
  2. Click on the gear icon in the top right corner
  3. Click OAuth from the drop-down menu
  4. Click the OAuth Apps tab
  5. Scroll to the application you'd like to access
  6. Under the Client Secret field, click the Reveal link

This will open a modal with the client_id and client_secret.

Specify connect URL parametersanchor

Redirect URIanchor

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

note

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

Scopeanchor

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.

In the special case where you are consenting to your own OAuth application, Braintree will automatically enforce an intersection between the requested scopes and the consenting user's current API privileges. If the intersection changes, the access token will be automatically revoked. The user must request a new access token to use the existing intersection.

Stateanchor

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 →