Account endpoints

Account endpoints manage who can use MapDove and how much. Most integrations only need GET /org/usage and key management; the rest power the app’s settings screens and are documented for completeness. Paths are relative to https://api.mapdove.com/api/v1.

Sessions vs API keys

	Session	API key
Created by	POST /auth/login or /auth/signup	POST /keys (or Settings → API keys)
Sent as	ms_session cookie (httpOnly, SameSite=Lax, Secure in production), or Authorization: Bearer <token>	Authorization: Bearer ms_live_<key>
Belongs to	a user	the organization (created by a user)
Intended for	the browser app, interactive use	servers, scripts, data pipelines
Counts API calls	no	yes, one per request
Account endpoints	all	rejected on session-only endpoints (below)
Ends	logout, expiry, password change	revocation

Use sessions for anything a person does in a browser and keys for everything automated.

Session-only endpoints

To keep a leaked key from taking over an account, these endpoints reject API keys with 403 forbidden and require a signed-in session:

• GET/PATCH /auth/me, POST /auth/password, POST /auth/2fa/*
• GET/PATCH /org, GET /org/audit, GET/POST/DELETE /org/members
• GET/POST/DELETE /keys
• POST /billing/checkout, POST /billing/portal

GET /org/usage accepts both, so integrations can monitor their quota.

Roles

Each user has an organization role:

Role	Can
owner	everything, including removing members and adding other owners
admin	rename the org, add members, manage API keys, manage billing
member	use all data and SDSS features, manage projects, favorites and alerts

Separately, MapDove staff have a platform role of admin for operating the service. Platform admin endpoints exist for operators only and are not part of the customer API.

Auth

Method	Path	Body	Response
POST	/auth/signup	{ email, password, name, company? }	201 Me + session cookie
POST	/auth/login	{ email, password, totp? }	200 Me + session cookie
POST	/auth/logout	–	204
GET	/auth/me	–	Me
PATCH	/auth/me	{ name?, locale?, theme?, default_city? }	Me
POST	/auth/password	{ current_password, new_password }	204
POST	/auth/2fa/setup	–	{ secret, otpauth_url }
POST	/auth/2fa/enable	{ code }	204
POST	/auth/2fa/disable	{ code }	204

• Passwords must be at least 10 characters.
• If two-factor authentication is on and totp is missing or wrong, login returns 401 with code totp_required.
• Repeated failed logins are throttled with 429 rate_limited.
• Locales: en, es, ar. Themes: system, light, dark, midnight, sand.

Log in and call the API with a session

curl -c cookies.txt -X POST https://api.mapdove.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.com", "password": "correct-horse-battery", "totp": "492011" }'

curl -b cookies.txt https://api.mapdove.com/api/v1/auth/me

Me

GET /auth/me — the current user, organization, plan limits and this month’s usage. Session only.

curl -b cookies.txt https://api.mapdove.com/api/v1/auth/me

{
  "user": {
    "id": "3b0f2c1e-9a8d-4c7b-b6e5-1f2a3d4c5b6a", "email": "ada@example.com", "name": "Ada Park",
    "role": "user", "org_role": "owner", "locale": "en", "theme": "system",
    "default_city": "austin", "totp_enabled": true, "created_at": "2026-09-14T08:30:00Z"
  },
  "org": { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "name": "Acme Retail", "plan": "pro", "suspended": false, "created_at": "2026-09-14T08:30:00Z" },
  "limits": {
    "history_days": 365, "analyses_per_month": 500, "api_calls_per_month": 10000,
    "api_keys": 3, "seats": 5, "exports": true, "cities": -1, "alerts": 10
  },
  "usage": { "month": "2026-11-01", "api_calls": 1284, "analyses": 37, "exports": 4 }
}

Organization

Method	Path	Body	Who
GET	/org	–	any member
PATCH	/org	{ name }	owner, admin
GET	/org/audit	?limit=50	any member

curl -X PATCH https://api.mapdove.com/api/v1/org \
  -b cookies.txt -H "Content-Type: application/json" \
  -d '{ "name": "Acme Retail Real Estate" }'

{ "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "name": "Acme Retail Real Estate", "plan": "pro", "suspended": false, "created_at": "2026-09-14T08:30:00Z" }

GET /org/audit returns the organization’s audit log — sign-ins, key creation and revocation, plan changes, new projects, member changes and exports:

[
  { "id": 9812, "org_id": "a1b2c3d4-…", "actor_email": "ada@example.com", "action": "key.create", "target": "ci-pipeline", "meta": {}, "ip": "203.0.113.7", "created_at": "2026-11-03T12:01:09Z" }
]

Members

Method	Path	Body	Who
GET	/org/members	–	any member
POST	/org/members	{ email, name, org_role, password }	owner, admin
DELETE	/org/members/:id	–	owner

Adding a member creates their account with the initial password you set; ask them to change it and enable two-factor authentication. Only owners can add other owners. Adding beyond the plan’s seat count returns 402 plan_limit.

curl -X POST https://api.mapdove.com/api/v1/org/members \
  -H "Cookie: ms_session=…" -H "Content-Type: application/json" \
  -d '{ "email": "lin@example.com", "name": "Lin Ortega", "org_role": "member", "password": "temporary-pass-2026" }'

{ "id": "7c6b5a4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "email": "lin@example.com", "name": "Lin Ortega", "org_role": "member", "created_at": "2026-11-06T09:00:00Z", "last_login_at": null }

API keys

Method	Path	Body	Who
GET	/keys	–	any member
POST	/keys	{ name }	owner, admin
DELETE	/keys/:id	–	owner, admin

curl -X POST https://api.mapdove.com/api/v1/keys \
  -H "Cookie: ms_session=…" -H "Content-Type: application/json" \
  -d '{ "name": "ci-pipeline" }'

{
  "key": { "id": "e4d3c2b1-a0f9-4e8d-8c7b-6a5f4e3d2c1b", "name": "ci-pipeline", "prefix": "ms_live_7Hq2", "created_at": "2026-11-03T12:01:09Z", "last_used_at": null, "revoked_at": null },
  "secret": "ms_live_7Hq2…"
}

The secret is shown only in this response; MapDove stores a hash. GET /keys lists keys with their prefix so you can tell them apart. DELETE /keys/:id revokes immediately (204) and the key keeps appearing in the list with revoked_at set. Active key counts are limited by plan (Pro 3, Business 10).

Usage

GET /org/usage — plan limits, this month’s counters and the last six months.

curl https://api.mapdove.com/api/v1/org/usage -H "Authorization: Bearer $MAPDOVE_KEY"

u = requests.get(f"{BASE}/org/usage", headers=H, timeout=30).json()
left = u["limits"]["api_calls_per_month"] - u["current"]["api_calls"]
print(f"{left} API calls left this month")

{
  "limits": { "history_days": 365, "analyses_per_month": 500, "api_calls_per_month": 10000, "api_keys": 3, "seats": 5, "exports": true, "cities": -1, "alerts": 10 },
  "current": { "month": "2026-11-01", "api_calls": 1285, "analyses": 37, "exports": 4 },
  "history": [
    { "month": "2026-10-01", "api_calls": 8120, "analyses": 211, "exports": 19 },
    { "month": "2026-09-01", "api_calls": 2304, "analyses": 96, "exports": 3 }
  ]
}

Counters reset on the first of each month (UTC). -1 means unlimited. Note that this call itself counts as an API call when made with a key.

Billing

Method	Path	Body	Who
POST	/billing/checkout	{ plan: "pro" | "business" }	owner, admin
POST	/billing/portal	–	owner, admin

POST /billing/checkout returns { url } — a hosted checkout page of our payment processor. Redirect the user there; when payment completes, the plan changes automatically. In installations where no payment processor is configured (for example local development), the plan is applied immediately and url is "/settings/billing?upgraded=1".

curl -X POST https://api.mapdove.com/api/v1/billing/checkout \
  -H "Cookie: ms_session=…" -H "Content-Type: application/json" \
  -d '{ "plan": "business" }'

{ "url": "https://checkout.payments.example/session/cs_…" }

POST /billing/portal returns { url } for the self-service billing portal, where owners and admins update payment methods, download invoices, change plan or cancel. Enterprise plans are arranged with sales and are not available through checkout.

A webhook endpoint receives signed events from the payment processor; it is not intended to be called by customers.