> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.yoco.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.yoco.com/_mcp/server.

# OAuth 2.0

OAuth 2.0 provides secure access to merchant resources through the Yoco API. This implementation
uses the 'authorization code flow', which enables applications to access merchant data on behalf of
the merchant after obtaining explicit authorisation.

## Supported flows

Yoco exclusively supports the OAuth 2.0
[authorization code flow](https://oauth.net/2/grant-types/authorization-code/).

The following flows aren't supported:

* [Proof Key for Code Exchange (PKCE)](https://oauth.net/2/pkce/)
* [Client Credentials](https://oauth.net/2/grant-types/client-credentials/)
* [Device Code](https://oauth.net/2/grant-types/device-code/)
* [Implicit Flow](https://oauth.net/2/grant-types/implicit/)
* [Password Grant](https://oauth.net/2/grant-types/password/)

### Authorization code flow

```mermaid
sequenceDiagram
    autonumber
    actor merchant as Yoco Merchant
    participant app as Your Application
    participant auth as Yoco Authorization Server

    Note over merchant,auth: AUTHORIZATION PHASE
    merchant->>app: Click install/connect

    Note over app: Generate and store state parameter<br />to prevent CSRF attacks
    app-->>auth: Redirect to authorization URL<br />/oauth2/auth
    Note right of auth: Required parameters:<br />client_id=your_client_id<br />redirect_uri=your_redirect_uri<br />response_type=code<br />scope=order_transactions.read<br />state=random_state_value

    auth->>merchant: Show login page

    opt Sign up flow (for new Yoco Merchants)
        merchant->>auth: Create new account
        auth->>merchant: Account creation process
    end

    merchant->>auth: Login
    auth->>merchant: Show consent screen
    Note right of auth: Displays:<br />1. Application name<br />2. Requested permissions<br />3. Data access scope
    merchant->>auth: Grant consent
    auth-->>app: Redirect with code<br />code=auth_code&state=state_value

    Note over app: Verify returned state matches<br />stored value before proceeding

    Note over app,auth: TOKEN EXCHANGE PHASE
    app-->>auth: POST /oauth2/token
    Note right of app: Required parameters:<br />grant_type=authorization_code<br />code=auth_code<br />client_id=your_client_id<br />client_secret=your_secret<br />redirect_uri=your_redirect_uri

    auth-->>app: Return tokens
    Note right of auth: Response contains:<br />access_token<br />refresh_token<br />id_token<br />expires_in<br />token_type=bearer<br />scope
    app-->>app: Store tokens
    Note right of app: Security requirements:<br />1. Store tokens securely<br />2. Never expose in frontend<br />3. Implement refresh flow<br />4. Use HTTPS for all requests

    app->>merchant: Complete installation
```

The diagram illustrates these critical phases:

#### Authorization request initiation

Your application redirects the merchant to Yoco's authorization server with required parameters
including client ID, scopes, and a state parameter for security.

#### Merchant authentication and consent

The merchant logs into their Yoco account and reviews the permissions your application is
requesting before granting access.

#### Authorization code exchange

Your application receives an authorization code and exchanges it for access tokens, id tokens
and refresh tokens using your client credentials.

## Requirements and limitations

### Token management

* Access tokens expire after **14 days**.
* Refresh tokens expire after **60 days**.
* Store tokens securely and never expose them to end users.

### Application approval

* You can create and test sandbox applications without approval.
* You need to submit live applications for review before going live.
* Each environment, whether sandbox or live, requires a separate application.

## Terminology

* **Access token**: A credential used to access protected resources.
* **Refresh token**: A credential used to obtain new access tokens.
* **Authorization code**: A short-lived code obtained during the authorisation process. It's
  exchanged for an access token at the end of the OAuth flow.
* **Client ID**: Your application's unique identifier.
* **Client secret**: A secret key used to authenticate your application. This is only displayed once
  when you create your application; make sure to store it securely.

See the official [OAuth 2.0 specification](https://datatracker.ietf.org/doc/html/rfc6749) for
details about OAuth 2.0 terminology.