Direct Integrator Authentication

This flow lets a direct integrator — a partner integrating their own single account (as opposed to an aggregator managing many accounts) — obtain the credentials needed to call the API.

It complements the existing auth documentation:

• API Essentials — Authentication — general OAuth 2.0 concepts used across the APIs.
• Guides — Quickstart — end-to-end walkthrough for aggregators.

If you are integrating multiple end-user accounts on behalf of your customers, use the aggregator (Authorization Code + PKCE) flow described in the guides above. If you are integrating your own single commercial account, use the flow described below.

• You have a commercial subscription.
• You are integrating your own account one seller, one integration.
• You want a low-friction way to obtain credentials without implementing the full authorization flow.

The flow has three steps:

1. Get a refresh token — you log into a hosted web portal with your account credentials. The portal displays a long-lived refresh token you copy into your backend.
2. Exchange the refresh token for an access token — your backend calls the token endpoint whenever it needs a new access token. Each call also returns a new refresh token that replaces the one you used.
3. Use the access token — send it as a Bearer header to any API endpoint, exactly like in the other auth flows.

┌────────────┐      1. Log in       ┌──────────────────────────┐
│  Operator  │ ───────────────────▶ │  Hosted portal           │
│ (browser)  │ ◀─── refresh token ──│  /realms/…/auth          │
└────────────┘                      └──────────────────────────┘
      │
      │ copy refresh token
      ▼
┌────────────┐                      ┌──────────────────────────┐
│  Partner   │ 2. POST /token       │   Token endpoint         │
│  backend   │ ───────────────────▶ │                          │
│            │ ◀── access + NEW ────│                          │
│            │     refresh token    └──────────────────────────┘
│            │
│            │ 3. Authorization: Bearer <access>
│            │ ───────────────────▶ Any API endpoint
└────────────┘

Open the portal in a browser:

https://iam.wallapop.com/realms/wallapop-connect/auth

Enter the email and password of the account you want to integrate with, and submit the form. On success, the portal displays your refresh token. Copy it into a secure store on your backend.

Keep the refresh token safe and treat it like a password.

Send a POST to the token endpoint each time you need a fresh access token:

curl -X POST 'https://iam.wallapop.com/realms/wallapop-connect/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'client_id=DirectIntegration' \
  --data-urlencode 'refresh_token=<YOUR_REFRESH_TOKEN>'

Successful response (200 OK):

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 300,
  "refresh_expires_in": 1209600,
  "refresh_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "scope": "openid basic offline_access"
}

Important fields:

Refresh tokens are single-use and rotate on every call:

1. You call /token with R1 → response contains new access token AND a new refresh token R2.
2. R1 is now invalidated. You must persist R2 and use it on the next call.
3. Next call with R2 → response returns R3. Persist R3, and so on.

If you present the same refresh token twice (either because you didn't persist the rotation, or because someone else copied it), the token is treated as compromised:

• The call returns 400 Bad Request with {"error": "invalid_grant"}.
• The entire session is revoked. Every refresh token that has ever been issued from this login is invalidated — including the one currently in your backend.
• Recovery: go back to Step 1 and log into the portal again to obtain a fresh refresh token.

For robust integration:

• Persist the new refresh token before treating the token call as successful.
• Serialize refresh calls per account (avoid two backend workers calling /token with the same refresh token in parallel).
• Handle invalid_grant by triggering an operator alert — the account owner must re-run Step 1.

Use the access token as a standard bearer token:

curl 'https://connect.wallapop.com/<endpoint>' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

Because access tokens expire in 5 minutes, most integrations refresh proactively — for example, refreshing every 4 minutes, or lazily on the first 401 response from an API call.

Two different integrations, two different flows:

If you're not sure, you're almost certainly an aggregator — keep reading this page. The direct-integrator flow is reserved for partners with a commercial subscription who want to authenticate their own account without implementing the full authorization flow.