Shop Pay wallet uses an OAuth-2.0-compliant flow to authenticate and obtain authorization from the user, and authorization code grant to obtain an `access_token`.

The Shop Pay Wallet API supports only [confidential applications](https://tools.ietf.org/html/rfc6749#section-2.1). A confidential application is usually a web server application that can hold a client secret. Credentials must be stored in a secure way without exposing them to unauthorized parties.

![Shop pay diagram](/assets/api/shop-pay/shop-pay-diagram.png)

## PKCE extension

OAuth 2.0 clients using authorization code grant can use the **Proof Key for Code Exchange (PKCE)** extension for OAuth [RFC7636](https://tools.ietf.org/html/rfc7636) to add an additional layer of security.

The PKCE extension works as follows:

1. At the start of the authorization flow, the client picks a _code verifier_ value. This can be any value.

2. During the authorization request, the client provides the authorization server with a _code challenge_ derived from the _code verifier_. The code challenge must be SHA-256.

4. During the access token request, the client provides the authorization server with the _code verifier_.

5. The authorization server verifies that the _code challenge_ matches the _code verifier_ before issuing an access token.

### Environment and variables

[RFC 8252 section 8.12](https://tools.ietf.org/html/rfc8252#section-8.12) explains the requirement for having an authentication-specific webview for OAuth inside native apps. Using this webview provides added security guarantees from the OS, and can provide a simpler login experience by reusing Shop Pay credentials obtained from the web.

We recommend that you use the AppAuth library ([https://appauth.io/](https://appauth.io/)) hosted in the OpenID github organization. It provides audited implementations for [iOS](https://github.com/openid/AppAuth-iOS) and [Android](https://github.com/openid/AppAuth-Android). If you do not want to use this library, then you must implement authorization using the most secure frameworks available.

#### iOS

Apple’s current API for authentication is [ASWebAuthenticationSession](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession) ([article](https://developer.apple.com/documentation/authenticationservices/authenticating_a_user_through_a_web_service)). It's been supported since iOS 12 (2018). The previous version of this API was SFAuthenticationSession.

#### Android

[Android Custom Tabs](https://developers.google.com/web/android/custom-tabs) is the best API provided by Android for creating authentication webviews. The header can optionally be themed, and we suggest using the Shop Pay primary color `#5a31f4` with white text.

#### Desktop and mobile web

For desktop or mobile web, we recommend that you use a browser pop-up to handle the authorization flow. The client can control the lifetime of the pop-up and dismiss it after it has obtained the authorization code.

## Related resources

- [Getting started](/docs/api/shop-pay-wallet/getting-started)
- [Shop Pay Wallet reference](/docs/api/shop-pay-wallet/reference/index)
- [Testing the integration](/docs/api/shop-pay-wallet/testing)
- [Shop Pay Wallet ecosystem](/docs/api/shop-pay-wallet/ecosystem)