Braintree Auth follows the OAuth 2.0 spec.
Redirect and authorization grant
After completion of the Connect flow, the merchant is sent to the redirectUri
you provide to connectUrl
. An authorization code is returned by Braintree in the query string, along with thestate
parameter you passed to connectUrl
.
Here is an example URL we would redirect to, given a redirectUri
of https://your.redirect.uri/callback
, and a state
of foo_state
:
https://your.redirect.uri/callback?state=foo_state&merchantId=g8cnjbnz83htzgm4&code=8b2cd3963a318b2e
Notice that you also receive back a merchantId
. This is a unique identifier for the account in Braintree's systems, so it can be very useful for support issues; it's also used to construct deep links to the Braintree Control Panel. See more details on merchantId
in the reference.
Getting an access token
You must exchange the authorization code in the query string for an accessToken
. The accessToken
is used to perform actions on a merchant's behalf. The following example creates an accessToken
:
const gateway = new braintree.BraintreeGateway({
clientId: "use_your_client_id",
clientSecret: "use_your_client_secret"
});
gateway.oauth.createTokenFromCode({
code: codeFromQueryString
}, (err, response) => {
const accessToken = response.credentials.accessToken;
const expiresAt = response.credentials.expiresAt;
const refreshToken = response.credentials.refreshToken;
});
Using an access token
You’ll use the access token to perform actions on the merchant’s behalf via the Merchant API.
Managing access tokens
The accessToken
will expire 24 hours from its creation. To exchange the accessToken
(e.g. if the current token is expiring soon or you think it has been compromised in some way), you can use the refreshToken
to get a new one. The refreshToken
is provided when you get the initial access token and will expire 180 days from its creation. Using a refreshToken
will give you both a new accessToken
and a new refreshToken
.
const gateway = new braintree.BraintreeGateway({
clientId: "use_your_client_id",
clientSecret: "use_your_client_secret"
});
gateway.oauth.createTokenFromRefreshToken({
refreshToken: useTheRefreshToken
}, (err, response) => {
const accessToken = response.credentials.accessToken;
const expiresAt = response.credentials.expiresAt;
const refreshToken = response.credentials.refreshToken;
});
You can then revoke the use of the original access token by providing it to the revoke access token API.
const gateway = new braintree.BraintreeGateway({
clientId: "use_your_client_id",
clientSecret: "use_your_client_secret"
});
gateway.oauth.revokeAccessToken(
merchantAccessToken,
(err, result) => {}
);
The connected merchant can revoke OAuth access via the Control Panel. You can be notified of this event by setting up the OAuth access revoked webhook.
Using a revoked access token on behalf of a merchant via the Merchant API will result in an authentication error.