# Authorization code with PKCE

How a customer connects their Ryde account to your application.

> **Note:** COMING SOON — not serving yet.

```
  Your application
        |
        |  redirect, with state + code_challenge
        v
  auth.ryde.us.com  ---->  customer signs in to Ryde
        |                    (you never see credentials)
        v
  Consent screen: the scopes you asked for, in plain language
        |
        |  customer approves
        v
  redirect back with ?code=... &state=...
        |
        |  POST /oauth/token  (+ code_verifier)
        v
  access_token (30 min, scoped)  +  refresh_token (rotating)
```

## Requirements

- Redirect URIs are matched EXACTLY against what you registered. No wildcards, no path prefixes, https only. A mismatch is refused on Ryde rather than redirected, so an attacker cannot use your client_id to bounce a code somewhere else.
- PKCE (S256) is required for public clients — mobile apps, single-page apps, anything that cannot keep a secret — and accepted for all clients. Use it everywhere.
- state is required, and you must verify it on the way back. It is your CSRF defence, not a convenience field.
- Authorization codes are single-use and expire in 60 seconds. A replayed code is refused.
- Refresh tokens rotate: each refresh returns a new one and invalidates the old. Store the newest and discard the previous.

## Disconnection

A customer can revoke your application from their Ryde account at any time, and you can revoke your own tokens at /oauth/revoke. Revocation applies to the GRANT, so it takes effect immediately for every token issued under it rather than waiting for one to expire.

> **Info:** Access tokens are short (30 minutes) and the grant behind them is checked on every request. Handle a 401 by refreshing once; if the refresh also fails, the customer has disconnected you and should be sent through the flow again rather than retried in a loop.