The web flow starts when your client redirects a user to the Mercury OAuth2 server that will verify client identity and let them confirm the authorization request.
The query parameters of the authorization URL are:
client_id- uniquely identifies your client.redirect_url- should match the registered client URL. It is also known as the Authorization callback URL.scope- specifies what type of access you need.state- random value that should be at least eight characters long.
The scope parameter contains a space-separated list of scopes that your client requests. Mercury supports two scopes:
- "read" — access the accounts and transactions.
- "offline_access" — required for refresh tokens.
Note: An access token has a short lifespan. A refresh token lets a client request a new access token without any user interaction. Add this scope if a client needs to maintain continuous access to the Mercury account.
Generate a random string for the query parameter state and store it. It's used to protect against cross-site request forgery. The client should verify its value when Mercury sends a user back.
If your client has PKCE, do the following as well:
- Generate a cryptographic random string that satisfies these requirements and store it. It's going to be used as
code_verifierwhen obtaining a token. - Calculate its SHA256 hash and convert it to base64. This is the value of the
code_challengequery parameter.