Developer API reference

Base URL: https://developerapi.motaware.com. Requests and responses are JSON, and every endpoint is versioned under /v1.

Authentication

Send one credential in the Authorization header:

Authorization: Bearer <credential>

The credential is one of:

An API key (starts with mwk_). It acts on the key owner's own Motaware account only, within the permissions chosen for the key. See API keys.
An access token your app got through Sign in with Motaware. It acts for the person who signed in, within the scopes they granted. Tokens issued to Motaware's own apps are not accepted.

If the person removes your app under Connected apps, calls fail immediately with 401 invalid_token. Revoking a key, turning a client off or suspending a project takes effect within about 30 seconds.

Endpoints

GET /v1/me

The caller's profile.

Credential	Scope needed
API key	`account.read`
Access token	`profile` or `email`

Field	When	Meaning
`id`	Always	The person's user id for your project: the same value as `sub` in your ID tokens. It is never the Motaware account id.
`email`, `email_verified`	`email` or `account.read`	Email address, and whether it is verified
`name`, `given_name`, `family_name`, `picture`	`profile` or `account.read`	Names and the profile photo URL. `family_name` and `picture` may be `null`.

{
  "id": "q7Tz0vX3mK8rP1sYwL5nB2dC9eF4gH6jA0uV7iO3kM8",
  "email": "dana@example.com",
  "email_verified": true,
  "name": "Dana Rivera",
  "given_name": "Dana",
  "family_name": "Rivera",
  "picture": null
}

GET /v1/me/plan

The caller's Motaware plan and what it includes. Scope: account.read. API keys can use it now. Outside apps will get it after app review, which is coming soon.

Field	Meaning
`plan_id`, `plan_display_name`	The plan, for example `personal` / "Personal"
`source`	Where the plan comes from: `own`, `family`, `organization`, or `free` when there is no paid plan
`state`	`Trial`, `Active`, `PastDue`, `CancelledPeriodActive`, `Cancelled`, `Expired`, or `free`
`read_only`	`true` while a lapsed plan is in its read-only window
`cache_max_age`	How many seconds you may cache this answer
`apps`	Slugs of the Motaware apps the plan includes
`addons`	Paid add-ons, such as Voices; `null` when the account has none
`entitlements`	Each feature mapped to `{ status, limit, unit }`. Status is `granted`, `granted_with_limit` or `denied`.

No account id is returned.

{
  "plan_id": "personal",
  "plan_display_name": "Personal",
  "source": "own",
  "state": "Active",
  "read_only": false,
  "cache_max_age": 3600,
  "apps": ["docs", "sheets", "calendar"],
  "addons": { "voices": null },
  "entitlements": {
    "storage.quota_gb": { "status": "granted_with_limit", "limit": 100, "unit": "gb" },
    "mail.custom_domain": { "status": "denied", "limit": null, "unit": null },
    "meet.recording": { "status": "granted", "limit": null, "unit": null }
  }
}

Examples

curl https://developerapi.motaware.com/v1/me \
  -H "Authorization: Bearer $MOTAWARE_API_KEY"

curl https://developerapi.motaware.com/v1/me/plan \
  -H "Authorization: Bearer $MOTAWARE_API_KEY"

Errors

Errors have this shape:

{ "error": { "code": "insufficient_scope", "message": "This endpoint needs the scope account.read." } }

Status	Code	When
401	`unauthenticated`	No credential was sent
401	`invalid_api_key`	The key is unknown, revoked or expired
401	`invalid_token`	The token is invalid or expired, access was removed, the client is off, or the token belongs to an app that isn't registered here
401	`project_suspended`	Motaware suspended the project
403	`insufficient_scope`	The credential lacks the scope. The `WWW-Authenticate` header lists the scopes that would work.
404	`not_found`	No such endpoint
429	`rate_limited`	Too many requests. Wait for the number of seconds in `Retry-After`.
502	`upstream_unavailable`	The service behind the endpoint is down. Try again shortly.

Rate limits

The API is free. These fair-use limits apply, in fixed one-minute windows:

600 requests per minute per API key or per app;
120 requests per minute per person within an app.

On 429, back off for the number of seconds in Retry-After. Refused calls count as errors in your usage.

CORS

Any origin may call the API from a browser: the credential travels in the Authorization header and no cookies are used. Never put an API key in browser code. Browser apps should use their user's access token.

Coming next

APIs for Calendar, Contacts, Tasks, Notes, Drive and Docs.