OAuth

Access Tokens

Availability

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

Once the merchant has agreed to your requested OAuth scopes, they'll be automatically sent to the redirect URI you specified when generating the connect URL. The final step in the OAuth sequence is for your server to use this redirect URI to create an OAuth access token for the merchant.

Values returned in the redirect URI

The redirect URI will include the following values as query parameters:

Query Parameter	Description
`code`	The authorization code. Must be exchanged for an access token to make API calls on the merchant's behalf.
`merchantId`	The Braintree identifier for the merchant's account. Used to construct deep links to the Braintree Control Panel and to help our Support team troubleshoot any issues you might encounter.
`state`	The `state` value you specified when generating the connect URL , if you specified one.

Creating an access token

You must exchange the authorization code in the query string of the RedirectUri for an AccessToken. The AccessToken is used to perform actions on a merchant's behalf. The following example creates an AccessToken:

BraintreeGateway gateway = new BraintreeGateway(
    "use_your_client_id",
    "use_your_client_secret"
);

var request = new OAuthCredentialsRequest {
    Code = codeFromQueryString
};

Result<OAuthCredentials> result = gateway.OAuth.CreateTokenFromCode(request);

string accessToken = result.Target.AccessToken;
DateTime expiresAt = result.Target.ExpiresAt.Value;
string refreshToken = result.Target.RefreshToken;

Managing access tokens

An OAuth 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.

BraintreeGateway gateway = new BraintreeGateway(
    "use_your_client_id",
    "use_your_client_secret"
);

var request = new OAuthCredentialsRequest {
    RefreshToken = useTheRefreshToken,
};

Result<oauthcredentials> result = gateway.OAuth.CreateTokenFromRefreshToken(request);
string accessToken = result.Target.AccessToken;
DateTime expiresAt = result.Target.ExpiresAt.Value;
string refreshToken = result.Target.RefreshToken;

You can then revoke the use of the original access token by providing it to the revoke access token API.

BraintreeGateway gateway = new BraintreeGateway(
    "use_your_client_id",
    "use_your_client_secret"
);

Result<oauthresult> result = gateway.OAuth.RevokeAccessToken(merchantAccessToken);

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 will result in an authentication error.

Next steps

See the OAuth Reference
Learn more about sharing access to payment methods in your own Vault using the Shared Vault and Grant API