Authorization code with PKCE

How a customer connects their Ryde account to your application.

API version v1 · View as Markdown

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.

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.