For apps
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.
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 athttps://login.mapit.me. - Discovery:
https://api.mapit.me/.well-known/oauth-protected-resource/v1names the authorization server; its metadata is athttps://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. Your next request answers
401.
