Creating authorization URLs | Yoco Developer Hub

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:

Environment	Authorization URL
Sandbox	`https://iam.yocosandbox.com/oauth2/auth`
Live	`https://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 URL-encoded list of permissions.
redirect_uri: Must exactly match the URL configured in your application.
state: Random value for Cross-Site Request Forgery (CSRF) protection.

Scopes

See the complete OAuth scopes documentation for all available options.

State parameter

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

Optional parameters

prompt: String (optional)
- Supported value: login
- Description: Forces the login screen to be shown even if the user has an active session. Useful when users need to connect multiple Yoco accounts to your application.

Example with prompt parameter

https://iam.yocosandbox.com/oauth2/auth
  ?client_id=YOUR_CLIENT_ID
  &response_type=code
  &scope=read_transactions
  &redirect_uri=https://yourapp.com/callback
  &state=RANDOM_STATE
  &prompt=login