# OAuth

Use OAuth when your app acts for Mapit customers other than you. Each customer signs in on Mapit's own page, sees what your app asks for and decides. Your app never sees their password.

> **Beta, free for now.** OAuth for apps is part of the Mapit API beta: details may change, and there is no uptime promise. See the [beta terms](https://developers.mapit.me/terms.md).

## The basics

- OAuth 2.1 authorization code flow with PKCE (`S256`). Public clients only: no client secret.
- Every authorization and token request carries `resource=https://api.mapit.me/v1`. A token is valid only for the resource it was issued for.
- Two hosts: the API at `https://api.mapit.me`, and sign-in and the OAuth endpoints at `https://login.mapit.me`.
- Discovery: [`https://api.mapit.me/.well-known/oauth-protected-resource/v1`](https://api.mapit.me/.well-known/oauth-protected-resource/v1) names the authorization server; its metadata is at [`https://login.mapit.me/.well-known/oauth-authorization-server`](https://login.mapit.me/.well-known/oauth-authorization-server).

## Scopes

| Scope | Gives |
| --- | --- |
| `mapit:read` | Account, vehicles and subscription. Required. |
| `mapit:location:read` | Last reported location and device status. |
| `mapit:routes:read` | Route history and ride statistics. |
| `offline_access` | A refresh token, so your app stays connected. |

Location and routes are checkboxes on the consent page, and the customer may leave them unticked. Read the `scope` in the token response to know what you got.

## 1. Register your app

Dynamic client registration accepts native apps that listen on a loopback address (RFC 8252):

```
curl -X POST https://login.mapit.me/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "My app", "redirect_uris": ["http://127.0.0.1:8765/callback"]}'
```

The port may change between runs; the path must be `/callback`. For a web app with an HTTPS redirect, ask us to add it: redirects are an allowlist, so nobody can pose as your app.

## 2. Send the customer to sign in

```
https://login.mapit.me/oauth/authorize
  ?response_type=code
  &client_id=CLIENT_ID
  &redirect_uri=http://127.0.0.1:8765/callback
  &code_challenge=BASE64URL(SHA256(verifier))
  &code_challenge_method=S256
  &resource=https://api.mapit.me/v1
  &scope=mapit:read mapit:location:read offline_access
  &state=RANDOM
```

Mapit redirects back with `code`, your `state` and `iss=https://login.mapit.me`, or with `error=access_denied` if the customer cancels.

## 3. Exchange the code

```
curl -X POST https://login.mapit.me/oauth/token \
  -d grant_type=authorization_code -d code=CODE -d client_id=CLIENT_ID \
  -d redirect_uri=http://127.0.0.1:8765/callback -d code_verifier=VERIFIER \
  -d resource=https://api.mapit.me/v1
```

The code works once, for one minute. The answer has `access_token` (15 minutes), `refresh_token` and `scope`.

## 4. Refresh

```
curl -X POST https://login.mapit.me/oauth/token \
  -d grant_type=refresh_token -d refresh_token=REFRESH_TOKEN \
  -d client_id=CLIENT_ID -d resource=https://api.mapit.me/v1
```

Each refresh token works once and comes back with a new one. Store the new one before using the access token. Sending a refresh token a second time ends the connection, because it means the token was copied: refresh from one place at a time.

## How long a connection lasts

- 30 days from the last refresh. An app that refreshes keeps it alive.
- One year from sign-in at most; then the customer signs in again.
- The customer can disconnect your app at any time on [login.mapit.me/connections](https://login.mapit.me/connections). Your next request answers `401`.
