AuthenticationOAuth 2.0

Creating authorization URLs

The authorization URL is the first step in the OAuth 2.0 flow. It directs merchants to Yoco’s authorization server, where they can authenticate and grant your application permission to access their data.

Authorization server endpoints

Use these endpoints based on your environment:

EnvironmentAuthorization URL
Sandboxhttps://iam.yocosandbox.com/oauth2/auth
Livehttps://iam.yoco.com/oauth2/auth

The examples below reference the Sandbox URL. Update as needed for your environment.

URL structure and parameters

Your authorization URL should follow this format:

https://iam.yocosandbox.com/oauth2/auth
  ?client_id=YOUR_CLIENT_ID
  &response_type=code
  &scope=YOUR_APPLICATIONS_REQUIRED_SCOPES
  &redirect_uri=YOUR_REDIRECT_URI
  &state=YOUR_STATE

The parameters in the URL must be URL-encoded.

Required parameters

  • client_id: Your application’s unique identifier from the developer console
  • response_type: Must be code for the authorization code flow
  • scope: Space-separated list of permissions (URL-encoded)
  • redirect_uri: Must exactly match the URL configured in your application
  • state: Random value for CSRF protection

Scopes

See the complete OAuth scopes documentation for all available options.

State parameter

State parameter management (generation, storage, and verification) is your application’s responsibility as part of CSRF protection.