idnits 2.17.1
draft-ietf-jmap-core-01.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
** The document seems to lack an IANA Considerations section. (See Section
2.2 of https://www.ietf.org/id-info/checklist for how to handle the case
when there are no actions for IANA.)
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (July 16, 2017) is 2475 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
-- Looks like a reference, but probably isn't: '1' on line 1924
-- Looks like a reference, but probably isn't: '2' on line 1926
-- Looks like a reference, but probably isn't: '3' on line 1928
-- Looks like a reference, but probably isn't: '4' on line 1930
-- Looks like a reference, but probably isn't: '5' on line 1932
-- Looks like a reference, but probably isn't: '6' on line 1934
** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615)
** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259)
Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 7 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 JMAP N. Jenkins
3 Internet-Draft FastMail
4 Intended status: Standards Track July 16, 2017
5 Expires: January 17, 2018
7 JSON Meta Application Protocol
8 draft-ietf-jmap-core-01
10 Abstract
12 This document specifies a protocol for synchronising JSON-based data
13 objects efficiently, with support for push and out-of-band binary
14 data upload/download.
16 Status of This Memo
18 This Internet-Draft is submitted in full conformance with the
19 provisions of BCP 78 and BCP 79.
21 Internet-Drafts are working documents of the Internet Engineering
22 Task Force (IETF). Note that other groups may also distribute
23 working documents as Internet-Drafts. The list of current Internet-
24 Drafts is at http://datatracker.ietf.org/drafts/current/.
26 Internet-Drafts are draft documents valid for a maximum of six months
27 and may be updated, replaced, or obsoleted by other documents at any
28 time. It is inappropriate to use Internet-Drafts as reference
29 material or to cite them other than as "work in progress."
31 This Internet-Draft will expire on January 17, 2018.
33 Copyright Notice
35 Copyright (c) 2017 IETF Trust and the persons identified as the
36 document authors. All rights reserved.
38 This document is subject to BCP 78 and the IETF Trust's Legal
39 Provisions Relating to IETF Documents
40 (http://trustee.ietf.org/license-info) in effect on the date of
41 publication of this document. Please review these documents
42 carefully, as they describe your rights and restrictions with respect
43 to this document. Code Components extracted from this document must
44 include Simplified BSD License text as described in Section 4.e of
45 the Trust Legal Provisions and are provided without warranty as
46 described in the Simplified BSD License.
48 Table of Contents
50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
51 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4
52 1.2. JSON as the data encoding format . . . . . . . . . . . . 4
53 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
54 1.3.1. User . . . . . . . . . . . . . . . . . . . . . . . . 5
55 1.3.2. Accounts . . . . . . . . . . . . . . . . . . . . . . 5
56 1.3.3. Data types and records . . . . . . . . . . . . . . . 5
57 1.4. Ids . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
58 1.5. The JMAP API model . . . . . . . . . . . . . . . . . . . 6
59 2. Authentication . . . . . . . . . . . . . . . . . . . . . . . 6
60 2.1. Service autodiscovery . . . . . . . . . . . . . . . . . . 6
61 2.2. Getting an access token . . . . . . . . . . . . . . . . . 7
62 2.2.1. 200: Success, but more authorization required. . . . 8
63 2.2.2. 201: Authentication is complete, access token
64 created. . . . . . . . . . . . . . . . . . . . . . . 11
65 2.2.3. 400: Malformed request . . . . . . . . . . . . . . . 13
66 2.2.4. 403: Authentication step failed, but client may try
67 again . . . . . . . . . . . . . . . . . . . . . . . . 14
68 2.2.5. 404: Not found . . . . . . . . . . . . . . . . . . . 14
69 2.2.6. 410: Restart authentication . . . . . . . . . . . . . 14
70 2.2.7. 429: Rate limited . . . . . . . . . . . . . . . . . . 14
71 2.2.8. 500: Internal server error . . . . . . . . . . . . . 14
72 2.2.9. 503: Service unavailable . . . . . . . . . . . . . . 14
73 2.3. Refetching URL endpoints . . . . . . . . . . . . . . . . 14
74 2.3.1. 201: Authentication is complete, access token
75 created. . . . . . . . . . . . . . . . . . . . . . . 15
76 2.3.2. 403: Restart authentication . . . . . . . . . . . . . 15
77 2.3.3. 404: Not found . . . . . . . . . . . . . . . . . . . 15
78 2.3.4. 500: Internal server error . . . . . . . . . . . . . 16
79 2.3.5. 503: Service unavailable . . . . . . . . . . . . . . 16
80 2.4. Revoking an access token . . . . . . . . . . . . . . . . 16
81 2.4.1. 204: Success . . . . . . . . . . . . . . . . . . . . 16
82 2.4.2. 401: Unauthorized . . . . . . . . . . . . . . . . . . 16
83 2.5. Authenticating HTTP requests . . . . . . . . . . . . . . 16
84 2.5.1. Signed GET requests . . . . . . . . . . . . . . . . . 17
85 3. Structured data exchange . . . . . . . . . . . . . . . . . . 17
86 3.1. Making an API request . . . . . . . . . . . . . . . . . . 18
87 3.1.1. 200: OK . . . . . . . . . . . . . . . . . . . . . . . 18
88 3.1.2. 400: Bad Request . . . . . . . . . . . . . . . . . . 18
89 3.1.3. 401: Unauthorized . . . . . . . . . . . . . . . . . . 18
90 3.1.4. 404: Not Found . . . . . . . . . . . . . . . . . . . 18
91 3.1.5. 413: Payload Too Large . . . . . . . . . . . . . . . 18
92 3.1.6. 429: Rate limited . . . . . . . . . . . . . . . . . . 19
93 3.1.7. 500: Internal Server Error . . . . . . . . . . . . . 19
94 3.1.8. 503: Service Unavailable . . . . . . . . . . . . . . 19
95 3.2. The structure of an API request . . . . . . . . . . . . . 19
96 3.3. Errors . . . . . . . . . . . . . . . . . . . . . . . . . 20
97 3.4. Vendor-specific extensions . . . . . . . . . . . . . . . 21
98 3.5. Security . . . . . . . . . . . . . . . . . . . . . . . . 21
99 3.6. Concurrency . . . . . . . . . . . . . . . . . . . . . . . 21
100 3.7. The Number datatype . . . . . . . . . . . . . . . . . . . 21
101 3.8. The Date datatypes . . . . . . . . . . . . . . . . . . . 22
102 3.9. Use of null . . . . . . . . . . . . . . . . . . . . . . . 22
103 3.10. CRUD methods . . . . . . . . . . . . . . . . . . . . . . 22
104 3.10.1. getFoos . . . . . . . . . . . . . . . . . . . . . . 22
105 3.10.2. getFooUpdates . . . . . . . . . . . . . . . . . . . 24
106 3.10.3. setFoos . . . . . . . . . . . . . . . . . . . . . . 26
107 3.11. Querying data . . . . . . . . . . . . . . . . . . . . . . 29
108 3.11.1. getFooList . . . . . . . . . . . . . . . . . . . . . 29
109 3.11.2. getFooListUpdates . . . . . . . . . . . . . . . . . 31
110 4. Downloading binary data . . . . . . . . . . . . . . . . . . . 33
111 4.1. 200: OK . . . . . . . . . . . . . . . . . . . . . . . . . 34
112 4.2. 401: Unauthorized . . . . . . . . . . . . . . . . . . . . 34
113 4.3. 404: Not Found . . . . . . . . . . . . . . . . . . . . . 34
114 4.4. 503: Service Unavailable . . . . . . . . . . . . . . . . 35
115 5. Uploading binary data . . . . . . . . . . . . . . . . . . . . 35
116 5.1. 201: File uploaded successfully . . . . . . . . . . . . . 35
117 5.2. 400: Bad request . . . . . . . . . . . . . . . . . . . . 36
118 5.3. 401: Unauthorized . . . . . . . . . . . . . . . . . . . . 36
119 5.4. 404: Not Found . . . . . . . . . . . . . . . . . . . . . 36
120 5.5. 413: Request Entity Too Large . . . . . . . . . . . . . . 36
121 5.6. 415: Unsupported Media Type . . . . . . . . . . . . . . . 36
122 5.6.1. 429: Rate limited . . . . . . . . . . . . . . . . . . 37
123 5.7. 503: Service Unavailable . . . . . . . . . . . . . . . . 37
124 6. Push . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
125 6.1. Event Source . . . . . . . . . . . . . . . . . . . . . . 38
126 6.2. Web hook . . . . . . . . . . . . . . . . . . . . . . . . 38
127 6.2.1. setPushCallback . . . . . . . . . . . . . . . . . . . 39
128 6.2.2. getPushCallback . . . . . . . . . . . . . . . . . . . 39
129 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 40
130 7.1. Normative References . . . . . . . . . . . . . . . . . . 40
131 7.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 41
132 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 41
134 1. Introduction
136 JMAP is a generic protocol for synchronising data, such as mail,
137 calendars or contacts, between a client and a server. It is
138 optimised for mobile and web environments, and aims to provide a
139 consistent interface to different data types.
141 This specification is for the generic mechanism of authentication and
142 synchronisation. Further specifications define the data models for
143 different data types that may be synchronised via JMAP.
145 JMAP is designed to make efficient use of limited network resources.
146 Multiple API calls may be batched in a single request to the server,
147 reducing round trips and improving battery life on mobile devices.
148 Push connections remove the need for polling, and an efficient delta
149 update mechanism ensures a minimum of data is transferred.
151 JMAP is designed to be horizontally scalable to a very large number
152 of users. This is facilitated by the separate end points for users
153 after login, the separation of binary and structured data, and a
154 shared data model that does not allow data dependencies between
155 accounts.
157 1.1. Notational Conventions
159 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
160 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
161 document are to be interpreted as described in [RFC2119].
163 The underlying format used for this specification is JSON.
164 Consequently, the terms "object" and "array" as well as the four
165 primitive types (strings, numbers, booleans, and null) are to be
166 interpreted as described in Section 1 of [RFC7159].
168 Some examples in this document contain "partial" JSON documents used
169 for illustrative purposes. In these examples, three periods "..."
170 are used to indicate a portion of the document that has been removed
171 for compactness.
173 Types signatures are given for all JSON objects in this document.
174 The following conventions are used:
176 o "Boolean|String" - The value is either a JSON "Boolean" value, or
177 a JSON "String" value.
179 o "Foo" - Any name that is not a native JSON type means an object
180 for which the properties (and their types) are defined elsewhere
181 within this document.
183 o "Foo[]" - An array of objects of type "Foo".
185 o "String[Foo]" - A JSON "Object" being used as a map (associative
186 array), where all the values are of type "Foo".
188 1.2. JSON as the data encoding format
190 JSON is a text-based data interchange format as specified in
191 [RFC7159]. The I-JSON format defined in [RFC7493] is a strict subset
192 of this, adding restrictions to avoid potentially confusing scenarios
193 (for example, it mandates that an object MUST NOT have two properties
194 with the same key).
196 All data sent from the client to the server or from the server to the
197 client (except binary file upload/download) MUST be valid I-JSON
198 according to the RFC, and is therefore case-sensitive and encoded in
199 UTF-8 ([RFC3629]).
201 1.3. Terminology
203 1.3.1. User
205 A user represents a set of permissions relating to what data can be
206 seen. To access data in JMAP, you first authenticate as a particular
207 user.
209 1.3.2. Accounts
211 An account is a collection of data.
213 All data, other than the Account objects themselves, belong to a
214 single account. A single account may contain an arbitrary set of
215 data, for example a collection of mail, contacts and calendars. Most
216 operations in JMAP are isolated to a single account; there are a few
217 explicit operations to copy data between them. Certain properties
218 are guaranteed for data within the same account, for example
219 uniqueness of ids within a type in that account.
221 An account is not the same as a user, although it is common for the
222 primary account to directly belong to the user. For example, you may
223 have an account that contains data for a group or business, to which
224 multiple users have access. Users may also have access to accounts
225 belonging to another user if that user is sharing some of their data.
227 1.3.3. Data types and records
229 JMAP provides a uniform interface for creating, retrieving, updating
230 and deleting various types of objects. A *data type* is a collection
231 of named, typed properties, just like the schema for a database
232 table. Each instance of a data type is called a *record*.
234 1.4. Ids
236 All object ids are assigned by the server, and are immutable. They
237 MUST be unique among all objects of the *same type* within the *same
238 account*. Ids may clash across accounts, or for two objects of
239 different types within the same account.
241 Ids are always "String"s. An id MUST be a valid UTF-8 string of at
242 least 1 character in length and maximum 256 bytes in size, but MUST
243 NOT start with the "#" character, as this is reserved for doing back
244 references during object creation (see the _setFoos_ description).
246 1.5. The JMAP API model
248 All data exchanges are authenticated using an access token.
249 Authentication is covered in section 2.
251 An authenticated client may exchange data with the server using four
252 different mechanisms:
254 1. The client may make an API request to the server to get or set
255 structured data. This request consists of an ordered series of
256 method calls. These are processed by the server, which then
257 returns an ordered series of responses. This is described in
258 section 3.
260 2. The client may download binary files from the server. This is
261 detailed in section 4.
263 3. The client may upload binary files to the server. This is
264 specified in section 5.
266 4. The client may connect to a push channel on the server, to be
267 notified when data has changed. This is explained in section 6.
269 2. Authentication
271 When connecting to any JMAP server, the client must first gain an
272 access token. It cannot just use a username/password directly. This
273 allows the server to know (and show the user) which clients currently
274 have access to the account, and to be able to revoke access
275 individually.
277 The server may support multiple different mechanisms for
278 authenticating a user to gain the access token. It is expected that
279 further types may be added in future extensions to the JMAP
280 specification.
282 2.1. Service autodiscovery
284 To begin authentication, the client needs to know the authentication
285 URL for the JMAP server.
287 There are two standardised autodiscovery methods in use for internet
288 protocols:
290 o *DNS srv* See [RFC6186] and [RFC6764]
292 o *.well-known/servicename* See [RFC5785]
294 A JMAP-supporting host for the domain "example.com" SHOULD publish a
295 SRV record "_jmaps._tcp.example.com" which gives a _hostname_ and
296 _port_ (usually port "443"). The authentication URL is then
297 "https://${hostname}[:${port}]/.well-known/jmap" (following any
298 redirects).
300 If the client has a username in the form of an email address, it MAY
301 use the domain portion of this to attempt autodiscovery of the JMAP
302 server.
304 To support clients that are unable to do SRV lookups, the server
305 SHOULD make the _hostname_ the same domain as the username if
306 possible.
308 2.2. Getting an access token
310 Authorization always starts with the client making a POST request to
311 the authentication URL (found either via service autodiscovery or
312 manual entry). The request MUST be of type "application/json" and
313 specify an "Accept: application/json" header. The body of the
314 request MUST be a single JSON object, encoded in UTF-8, with the
315 following properties:
317 o *username*: "String" The username the client wishes to
318 authenticate. This is normally the primary email address of the
319 user.
321 o *clientName*: "String" The name of the client software. e.g.
322 "Mozilla Thunderbird".
324 o *clientVersion*: "String" Information to identify the version of
325 the client. This MUST change for any changed client code (e.g. a
326 version control tag or counter for development software) and
327 SHOULD sort lexically later for newer versions.
329 o *deviceName*: "String" A human-friendly string to identify the
330 device making the request, e.g. "Joe Blogg's iPhone".
332 The server may use the client/device information to help identify the
333 login to the user in a login log or other security reporting.
334 Although hopefully unnecessary, they may also be helpful for working
335 around client bugs in the future.
337 The server will respond with one of the following HTTP status codes:
339 2.2.1. 200: Success, but more authorization required.
341 The response body will be a single JSON object with the following
342 properties.
344 o *loginId*: "String" An id from the server to allow it to connect
345 the next request with previous requests in the login process.
346 This SHOULD be of limited time validity (e.g. 15 minutes from
347 previous call).
349 o *methods*: "AuthMethod[]" A list of the supported authentication
350 methods to continue with authentication. See below for definition
351 of the *AuthMethod* object.
353 o *prompt*: "String|null" A message to display in the client to the
354 user. The client MUST treat this as plain text, but SHOULD
355 automatically hyperlink any URLs it finds if a system browser is
356 available.
358 This is the standard response to an initial request. Note, a server
359 may return this even if the username is not actually active, to
360 prevent enumeration. The client should then pick one of the
361 _methods_ from the list in the response to continue with
362 authentication (if no methods supported by the client are in the
363 list, it will not be able to get an access token).
365 An *AuthMethod* object MUST have a *type* property. This is a
366 "String" representing the method of authentication. For some types,
367 there may be other values required on the AuthMethod object in
368 addition; see the description of types below. The following types
369 are currently defined, but more may be added in the future. A client
370 SHOULD offer the user the option to choose any of the method types
371 returned that the client supports. The client MUST ignore any types
372 it does not understand:
374 o "external": The user must do something out-of-band to authorize
375 the app. The server SHOULD use the _prompt_ property of the
376 response to tell the user what they need to do. A client that
377 supports the _external_ authorisation type MUST offer a mechanism
378 for the user to indicate to the client when they have completed
379 the out-of-band authentication.
381 o "oauth": OAuth based authentication. For OAuth integration, see
382 the docs of the service in question, since every service
383 implements it slightly differently and the client must register
384 with the service beforehand to use it. If using this method, an
385 access token is obtained entirely through the OAuth mechanism from
386 this point on, and requests will be authenticated as per the OAuth
387 spec. See the "Refetching URL endpoints" section below for how to
388 obtain the URL endpoints after successfully authenticating using
389 OAuth.
391 o "password": The user must input their current password for the
392 account.
394 o "totp": The user must input a TOTP [1] code from a device
395 registered with the account.
397 o "yubikeyotp": The user must input a Yubico OTP [2] code from a
398 Yubikey registered with the account.
400 o "u2f": The user must sign a challenge using a FIDO U2F [3] key
401 registered with the account. The AuthMethod object for this type
402 MUST also have the following properties:
404 * *appId*: "String" The app id to use.
406 * *signChallenge*: "String" The challenge to be signed by the U2F
407 key.
409 * *registeredKeys*: "RegisteredKey[]" The keys associated with
410 this user. A *RegisteredKey* object has the following
411 properties:
413 * *version*: "String" The U2F protocol version.
415 * *keyHandle*: "String" The key handle of the registered key.
417 o "sms": The user must input a one-time code sent via SMS to a phone
418 number registered with the account. The AuthMethod object for
419 this type MUST also have the following property:
421 * *phoneNumbers*: "LoginPhone[]|null" An array of *LoginPhone*
422 objects, each of which represents a phone registered with the
423 account. A *LoginPhone* object has the following properties:
425 + *id*: "String" The id of the phone. This is used when
426 asking the server to send a code.
428 + *number*: "String" The phone number to display to the user
429 to remind them which number the SMS will be/was sent to.
430 This MAY have some characters replaced with an "X" or other
431 "blanked-out" character if the server does not wish to
432 disclose the full phone number at this point. e.g. if the
433 phone registered with the account is "+61 123 456 789", the
434 server might return "+61 1XX XXX X89" as the number.
436 + *isCodeSent*: "Boolean" Has the verification code been sent
437 to this number yet? The server MAY choose to send the SMS
438 before the first time this auth option is returned, or may
439 wait for the user to explicitly request it.
441 If not using ""oauth"", the user will at some point indicate to the
442 client to continue authentication (after inputing any required
443 token/code/password dependent on the auth method chosed). At this
444 point the client submits a POST request to the same URL as before,
445 with the body being a single JSON object with the following
446 properties:
448 o *loginId*: "String" The _loginId_ the server sent from the
449 previous request.
451 o *type*: "String" The type of the method chosen to continue
452 authentication.
454 o *value*: "*" The value as appropriate for the given type:
456 * "external": "null"
458 * "password"/"totp"/"yubikeyotp"/"sms": "String" - the password/
459 one-time code.
461 * "u2f": "SignResponse" - an object with _keyHandle_,
462 _signatureData_ and _clientData_ "String" properties, as
463 defined in the U2F spec.
465 Note: The client SHOULD NOT store any password/code the user has
466 entered beyond what is required to submit it to the server in this
467 step.
469 The server will then return one of the same set of responses as
470 before, which should be handled the same (for example, if two-factor
471 authentication is required, a "200" response may be returned again
472 and TOTP/U2F prompted for).
474 If the user chooses to authenticate using SMS, they may need to
475 request the server to send the code to a particular number before
476 they can submit a code. To do this, the client submits a POST
477 request to the same URL as before, with the body being a single JSON
478 object with the following properties:
480 o *loginId*: "String" The _loginId_ the server sent from the
481 previous request.
483 o *sendCodeTo*: "String" The id of the phone number to send the code
484 to.
486 The server SHOULD send the code to the given phone if the phone id is
487 valid. If the code has already been sent, it is server-dependent
488 whether it is sent again or ignored. The server MUST return one of
489 the same set of responses as before, which should be handled the same
490 (in most cases this will be a "200" response identical to before
491 except that the _isCodeSent_ property for the phone will now be
492 "true").
494 2.2.2. 201: Authentication is complete, access token created.
496 The response body will be a single JSON object with the following
497 properties.
499 o *username*: "String" The username that was successfully
500 authenticated.
502 o *accessToken*: "String" The secret token to be used by the client
503 to authenticate all future JMAP requests. The client should keep
504 this secure, preferably in an OS keychain or the like. Since
505 tokens should not be reused across devices or clients, the client
506 SHOULD NOT reveal this token to the user.
508 o *signingId*: "String" The id to put in the JWT [4] for signed GET
509 requests (see below). This is used to allow the server to find
510 the session so it can find the signing key to use to verify the
511 token. You MUST NOT be able to derive the _accessToken_ or
512 _signingKey_ from the _signingId_.
514 o *signingKey*: "String" The secret key to use for signing the JWT
515 [5] for signed GET requests (see below), encoded as base64url as
516 specified in ([RFC4648]). The client should keep this secure,
517 preferably in an OS keychain or the like. Since keys should not
518 be reused across devices or clients, the client SHOULD NOT reveal
519 this token to the user.
521 o *accounts*: "String[Account]" A map of *account id* to Account
522 object for each account the user has access to. A single access
523 token may provide access to multiple accounts, for example if
524 another user is sharing their mail with the logged in user, or if
525 there is an account that contains data for a group or business.
526 All data belongs to a single account. With the exception of a few
527 explicit operations to copy data between accounts, all JMAP
528 methods take an _accountId_ argument that specifies on which
529 account the operations are to take place. This argument is always
530 optional; if not specified, the primary account is used. All ids
531 (other than Account ids of course) are only unique within their
532 account. In the event of a severe internal error, a server may
533 have to reallocate ids or do something else that violates standard
534 JMAP data constraints. In this situation, the data on the server
535 is no longer compatible with cached data the client may have from
536 before. The server MUST treat this as though the account has been
537 deleted and then recreated with a new account id. Clients will
538 then be forced to throw away any data with the old account id and
539 refetch all data from scratch. An *Account* object has the
540 following properties:
542 * *name*: "String" A user-friendly string to show when presenting
543 content from this account, e.g. the email address representing
544 the owner of the account.
546 * *isPrimary*: "Boolean" This MUST be true for *at most* one of
547 the accounts returned. This is to be considered the user's
548 main or default account by the client. If no account being
549 returned belongs to the user, or in any other way there is no
550 appropriate way to determine a default account, then this MAY
551 be "false" for all accounts.
553 * *isReadOnly*: "Boolean" This is "true" if the entire account is
554 read-only.
556 * *hasDataFor*: "String[]" A list of the data profiles available
557 in this account. Each future JMAP data types specification
558 will define a profile name to encompass that set of types.
560 o *capabilities*: "String[Object]" An object specifying the
561 capabilities of this server. The keys are URIs, which specify the
562 specifications supported by the server. The value for each of
563 these keys is an object that MAY include further information about
564 the server's capabilities in relation to that spec. The client
565 MUST ignore any properties it does not understand. The
566 capabilities object MUST include a property called "{TODO: URI for
567 this spec}". The value of this property is an object which SHOULD
568 contain the following information on server capabilities:
570 * *maxSizeUpload*: "Number" The maximum file size, in bytes, that
571 the server will accept for a single file upload (for any
572 purpose).
574 * *maxConcurrentUpload*: "Number" The maximum number of
575 concurrent requests the server will accept to the upload
576 endpoint.
578 * *maxSizeRequest*: "Number" The maximum size, in bytes, that the
579 server will accept for a single request to the API endpoint.
581 * *maxConcurrentRequests*: "Number" The maximum number of
582 concurrent requests the server will accept to the API endpoint.
584 * *maxCallsInRequest*: "Number" The maximum number of method
585 calls the server will accept in a single request to the API
586 endpoint.
588 * *maxObjectsInGet*: "Number" The maximum number of obje ts that
589 the client may request in a single "getFoos" type method call.
591 * *maxObjectsInSet*: "Number" The maximum number of objects the
592 client may send to create, update or destroy in a single
593 "setFoos" type method call.
595 Future specifications will define their own properties on the
596 capabilities object.
598 o *apiUrl*: "String" The URL to use for JMAP API requests.
600 o *downloadUrl*: "String" The URL endpoint to use when downloading
601 files (see the Download section of this spec), in [RFC6570] URI
602 Template (level 1) format. The URL MUST contain variables called
603 "accountId" and "blobId". The URL SHOULD contain a variable
604 called "name".
606 o *uploadUrl*: "String" The URL endpoint to use when uploading files
607 (see the Upload section of this spec).
609 o *eventSourceUrl*: "String" The URL to connect to for push events
610 (see the Push section of this spec).
612 URLs are returned only after logging in. This allows different URLs
613 to be used for users located in different geographic datacentres
614 within the same service.
616 Note, if authentication is done via IP or mobile subscriber ID or
617 some similar mechanism, a "201" response MAY be returned in response
618 to the initial request (with just the username and client info).
620 2.2.3. 400: Malformed request
622 The request is of the wrong content type, or does not contain data in
623 the expected format. The client MUST NOT retry the same request.
624 There is no content in the response.
626 2.2.4. 403: Authentication step failed, but client may try again
628 Returned in response to a continuation request which failed (e.g. the
629 password entered was not correct, or the out-of-band step was not
630 completed successfully). The response body will be a single JSON
631 object with the same properties as the "200" response, and the client
632 may try again.
634 2.2.5. 404: Not found
636 The JMAP authentication server is not available at this address. The
637 client needs to rediscover the authentication URL. There is no
638 content in the response.
640 2.2.6. 410: Restart authentication
642 The login attempt has failed permanently. This may be due to a
643 password being incorrect, the login id expiring, or any other reason.
644 The client MUST restart authentication (go back to sending the
645 username and client info to the server). There is no content in the
646 response.
648 2.2.7. 429: Rate limited
650 Returned if the server is temporarily blocking this IP/client from
651 authenticating. This may be due to too many failed password
652 attempts, or detected username enumeration attempts, or any other
653 reason. (Legitimate) clients should wait a while then try again.
654 There is no content in the response.
656 2.2.8. 500: Internal server error
658 Something has gone wrong internally, and the server is in a broken
659 state. Don't automatically retry. There is no content in the
660 response.
662 2.2.9. 503: Service unavailable
664 The server is currently down. Try again later with exponential
665 backoff. There is no content in the response.
667 2.3. Refetching URL endpoints
669 A server MAY (although SHOULD NOT) move end points for any services
670 other than authentication at any time. If a request to the API/file
671 upload/event source endpoint returns a "404", the client MUST refetch
672 the URL endpoints. To do this, it should make an authenticated GET
673 request to the authentication URL (see below for how to authenticate
674 requests).
676 For OAuth logins, this is how the URLs may be fetched initially as
677 well.
679 The server MUST respond with one of the following status codes:
681 2.3.1. 201: Authentication is complete, access token created.
683 The request was successful. The response will be of type
684 "application/json" and consists of a single JSON object containing
685 the following properties:
687 o *username*: "String" The username that was successfully
688 authenticated.
690 o *accounts*: "String[Account]" An object representing the accounts
691 the user has access to. See the full description above.
693 o *capabilities*: "String[Object]" An object specifying the
694 capabilities of this server. See the full description above.
696 o *apiUrl*: "String" The URL to use for JMAP API requests.
698 o *downloadUrl*: "String" The URL endpoint to use when downloading
699 files (see above).
701 o *uploadUrl*: "String" The URL endpoint to use when uploading files
702 (see the Upload section of this spec).
704 o *eventSourceUrl*: "String" The URL to connect to for push events
705 (see the Push section of this spec).
707 2.3.2. 403: Restart authentication
709 The "Authorization" header was missing or did not contain a valid
710 token. Reauthenticate and then retry the request. There is no
711 content in the response.
713 2.3.3. 404: Not found
715 The JMAP server is no longer here. There is no content in the
716 response.
718 2.3.4. 500: Internal server error
720 Something has gone wrong internally, and the server is in a broken
721 state. Don't automatically retry. There is no content in the
722 response.
724 2.3.5. 503: Service unavailable
726 The server is currently down. Try again later with exponential
727 backoff. There is no content in the response.
729 2.4. Revoking an access token
731 The validity of an access token is determined by the server. It may
732 be valid for a limited time only, or expire after a certain time of
733 inactivity, or be valid indefinitely etc. If an access token
734 expires, it MUST NOT be resurrected. The client MUST restart the
735 authentication process to get a new access token.
737 For OAuth, see the provider's documentation on revoking access
738 tokens.
740 Otherwise, a client may revoke an access token at any time by making
741 an authenticated DELETE HTTP request to the authentication URL (the
742 one used to get the token in the first place). The response from the
743 server will be one of the following:
745 2.4.1. 204: Success
747 The access token has now been revoked. There is no content in the
748 response.
750 2.4.2. 401: Unauthorized
752 Failed due to missing "Authorization" header, or the "Authorization"
753 header did not contain a valid access token. As per the HTTP spec,
754 the response MUST have a "WWW-Authenticate: Bearer" header. There is
755 no content in the response.
757 2.5. Authenticating HTTP requests
759 All HTTP requests other than to the authentication URL must be
760 authenticated. To do this, the client MUST add an "Authorization"
761 header to each request.
763 Once authenticated, the client will have an access token. This is
764 used with the "Bearer" scheme as specified in [RFC6750] to
765 authenticate HTTP requests.
767 For example, if _user@example.com_ successfully logged in and the
768 client received an _accessToken_ of "abcdef1234567890", to
769 authenticate requests you would add the following header:
771 Authorization: Bearer abcdef1234567890
773 2.5.1. Signed GET requests
775 Sometimes, particularly in the browser context, authenticating a GET
776 request using the usual "Authorization" header is not easily
777 implemented. In such situations, a client may use a signed request
778 instead.
780 Instead of the "Authorization" header, a signed request has an
781 "access_token" query parameter, the value of which is an [RFC7519]
782 JSON Web Token [6] constructed as follows:
784 o The algorithm MUST be HMAC SHA-256.
786 o The JWT MUST contain the following set of claims:
788 * *iss*: "String" The _signingId_ value returned after
789 authentication.
791 * *sub*: "String" The origin + path of the URL being signed,
792 (i.e. the full URL excluding query parameters).
794 * *iat*: "Number" The time the client created this JWT, in
795 seconds since 1970-01-01T00:00:00Z.
797 o The JWT MUST be signed using the _signingKey_ returned after
798 authentication as the key.
800 To verify, a server MUST: * Ensure the algorithm is set to HMAC SHA-
801 256. * Verify the URL being requested matches that in the _sub_
802 claim. * Decode the payload and look up the session using the _iss_
803 claim, ensure it is still valid, and then verify the JWT signature is
804 valid using the session's _signingKey_.
806 The server MAY choose to only allow tokens to be valid for a limited
807 amount of time after the client created it, as determined by the
808 _iat_ claim.
810 3. Structured data exchange
812 The client may make an API request to the server to get or set
813 structured data. This request consists of an ordered series of
814 method calls. These are processed by the server, which then returns
815 an ordered series of responses.
817 3.1. Making an API request
819 To make an API request, the client makes an authenticated POST
820 request to the API URL; see the Authentication section of the spec
821 for how to discover this URL and how to authenticate requests.
823 The request MUST have a content type of "application/json" and be
824 encoded in UTF-8.
826 The server SHOULD respond with one of the following HTTP response
827 codes:
829 3.1.1. 200: OK
831 The API request was successful. The response will be of type
832 "application/json" and consists of the response to the API calls, as
833 described below.
835 3.1.2. 400: Bad Request
837 The request was malformed. For example, it may have had the wrong
838 content type, or have had a JSON object that did not conform to the
839 API calling structure (see _The structure of an API request_ below).
840 The client SHOULD NOT retry the same request. There is no content in
841 the response.
843 3.1.3. 401: Unauthorized
845 The "Authorization" header was missing or did not contain a valid
846 token. Reauthenticate and then retry the request. As per the HTTP
847 spec, the response MUST have a "WWW-Authenticate" header listing the
848 available authentication schemes. There is no content in the
849 response.
851 3.1.4. 404: Not Found
853 The API endpoint has moved. See the Authentication section of the
854 spec for how to rediscover the current URL to use. There is no
855 content in the response.
857 3.1.5. 413: Payload Too Large
859 Returned if the client makes a request with more method calls than
860 the server is willing to accept in a single request, or if the total
861 bytes of the request is larger than the max size the server is
862 willing to accept.
864 3.1.6. 429: Rate limited
866 Returned if the client has made too many requests recently, or has
867 too many concurrent requests currently in progress. Clients SHOULD
868 wait a while then try again. The response MAY include a "Retry-
869 After" header indicating how long to wait before making a new
870 request.
872 3.1.7. 500: Internal Server Error
874 Something has gone wrong internally, and the server is in a broken
875 state. Don't automatically retry. There is no content in the
876 response.
878 3.1.8. 503: Service Unavailable
880 The server is currently down. Try again later with exponential
881 backoff. There is no content in the response.
883 3.2. The structure of an API request
885 The client initiates an API request by sending the server a JSON
886 array. Each element in this array is another array representing a
887 method invocation on the server. The server will process the method
888 calls and return a response consisting of an array in the same
889 format. Each method call always contains three elements:
891 1. The *name* of the method to call, or the name of the response
892 from the server. This is a "String".
894 2. An "Object" containing _named_ *arguments* for that method or
895 response.
897 3. A *client id*: an arbitrary "String" to be echoed back with the
898 responses emitted by that method call (as we'll see lower down, a
899 method may return 1 or more responses, as some methods make
900 implicit calls to other ones).
902 Example query:
904 [
905 ["method1", {"arg1": "arg1data", "arg2": "arg2data"}, "#1"],
906 ["method2", {"arg1": "arg1data"}, "#2"],
907 ["method3", {}, "#3"]
908 ]
910 The method calls MUST be processed sequentially, in order. Each API
911 request (which, as shown, may contain multiple method calls) receives
912 a JSON response in exactly the same format. The output of the
913 methods MUST be added to the array in the same order as the methods
914 are processed.
916 Example response:
918 [
919 ["responseFromMethod1", {"arg1": 3, "arg2": "foo"}, "#1"],
920 ["responseFromMethod2", {"isBlah": true}, "#2"],
921 ["anotherResponseFromMethod2", {
922 "data": 10,
923 "yetmoredata": "Hello"
924 }, "#2"],
925 ["aResponseFromMethod3", {}, "#3"]
926 ]
928 3.3. Errors
930 If the data sent as an API request is not valid JSON or does not
931 match the structure above, an error will be returned at the transport
932 level. For example, when using JMAP over HTTP, a "400 Bad Request"
933 error will be returned at the HTTP level.
935 Possible errors for each method are specified in the method
936 descriptions. If a method encounters an error, the appropriate
937 "error" response MUST be inserted at the current point in the output
938 array and, unless otherwise specified, further processing MUST NOT
939 happen within that method call.
941 Any further method calls in the request MUST then be processed as
942 normal.
944 An "error" response looks like this:
946 ["error", {
947 type: "unknownMethod"
948 }, "client-id"]
950 The response name is "error", and it has a type property as specified
951 in the method description. Other properties may be present with
952 further information; these are detailed in the method descriptions
953 where appropriate.
955 Any method MAY return an error of type "serverError" if an unexpected
956 or unknown error occurs during the processing of that call. The
957 state of the server after such an error is undefined.
959 If an unknown method is called, an "unknownMethod" error (this is the
960 type shown in the example above) MUST be inserted and then the next
961 method call MUST be processed as normal.
963 If an unknown argument or invalid arguments (wrong type, or in
964 violation of other specified constraints) are supplied to a method,
965 an "invalidArguments" error MUST be inserted and then the next method
966 call MUST be processed as normal.
968 3.4. Vendor-specific extensions
970 Individual services will have custom features they wish to expose
971 over JMAP. This may take the form of extra datatypes and/or methods
972 not in the spec, or extra arguments to JMAP methods, or extra
973 properties on existing data types (which may also appear in arguments
974 to methods that take property names). To ensure compatibility with
975 clients that don't know about a specific custom extension, and for
976 compatibility with future versions of JMAP, the server MUST ONLY
977 expose these extensions if the client explicitly opts in. Without
978 opt-in, the server MUST follow the spec and reject anything that does
979 not conform to it as specified.
981 3.5. Security
983 As always, the server must be strict about data received from the
984 client. Arguments need to be checked for validity; a malicious user
985 could attempt to find an exploit through the API. In case of invalid
986 arguments (unknown/insufficient/wrong type for data etc.) the method
987 MUST return an "invalidArguments" error and terminate.
989 3.6. Concurrency
991 To ensure the client always sees a consistent view of the data, the
992 state accessed by a method call MUST NOT change during the execution
993 of the method, except due to actions by the method call itself. The
994 state MAY change in-between method calls (even within a single API
995 request).
997 3.7. The Number datatype
999 The JSON datatypes are limited to those found in JavaScript. A
1000 "Number" in JavaScript is represented as a signed double (64-bit
1001 floating point). However, except where explicitly specified, all
1002 numbers used in this API are unsigned integers <= 2^53 (the maximum
1003 integer that may be reliably stored in a double). This implicitly
1004 limits the maximum length of message lists in queries and the like.
1006 3.8. The Date datatypes
1008 Where a JMAP API specifies "Date" as a type, it means a string in
1009 [RFC3339] _date-time_ format, with the _time-offset_ component always
1010 "Z" (i.e. the date-time MUST be in UTC time) and _time-secfrac_
1011 always omitted. The "T" and "Z" MUST always be upper-case. For
1012 example, ""2014-10-30T14:12:00Z"".
1014 3.9. Use of null
1016 Unless otherwise specified, a missing property in the arguments
1017 object of a request (from the client), or a response (from the
1018 server) MUST be intepreted exactly the same as that property having
1019 the value "null".
1021 Unless otherwise specified, a missing property in a data object MUST
1022 be interpreted in the following ways: - In the response to a
1023 _getFoos_ style call, or when *creating* an object in a _setFoos_
1024 style call, a missing property MUST be interpreted as though it had
1025 the default value for that type, or "null" if no default is
1026 specified. - When *updating* an object in a _setFoos_ style call, a
1027 missing property MUST be interpreted as the existing value for that
1028 property (i.e. don't update it).
1030 For network efficiency, when fetching the server and client may make
1031 use of the above and omit properties which have the default value for
1032 the data type.
1034 3.10. CRUD methods
1036 JMAP provides a uniform interface for creating, retrieving, updating
1037 and deleting various types of objects. For a "Foo" data type,
1038 records of that type would be fetched via a "getFoos" call and
1039 modified via a "setFoos" call. Delta updates may be fetched via a
1040 "getFooUpdates" call. These methods all follow a standard format as
1041 described below.
1043 3.10.1. getFoos
1045 Objects of type *Foo* are fetched via a call to _getFoos_. Methods
1046 with a name starting with "get" MUST NOT alter state on the server.
1048 This method may take some or all of the following arguments; see the
1049 definition of the data type in question. However, if one of the
1050 following arguments is available, it will behave exactly as specified
1051 below.
1053 o *accountId*: "String|null" The id of the Account to use. If
1054 "null", the primary account is used.
1056 o *ids*: "String[]|null" The ids of the Foo objects to return. If
1057 "null" then *all* records of the data type are returned, if this
1058 is supported for that data type.
1060 o *properties*: "String[]|null" If supplied, only the properties
1061 listed in the array are returned for each Foo object. If "null",
1062 all properties of the object are returned. The id of the object
1063 is *always* returned, even if not explicitly requested.
1065 The response to "getFoos" is called "foos". It has the following
1066 arguments:
1068 o *accountId*: "String" The id of the account used for the call.
1070 o *state*: "String" A string representing the state on the server
1071 for *all* the data of this type. If the data changes, this string
1072 will change. It is used to get delta updates, if supported for
1073 the type.
1075 o *list*: "Foo[]" An array of the Foo objects requested. This is
1076 the *empty array* if no objects were found, or if the _ids_
1077 argument passed in was also the empty array.
1079 o *notFound*: "String[]|null" This array contains the ids passed to
1080 the method for records that do not exist. This property is "null"
1081 if all requested ids were found, or if the _ids_ argument passed
1082 in was either "null" or the empty array.
1084 The following error may be returned instead of the "foos" response:
1086 "accountNotFound": Returned if an _accountId_ was explicitly included
1087 with the request, but it does not correspond to a valid account.
1089 "accountNotSupportedByMethod": Returned if the _accountId_ given
1090 corresponds to a valid account, but the account does not support this
1091 data type.
1093 "requestTooLarge": Returned if the number of _ids_ requested by the
1094 client exceeds the maximum number the server is willing to process in
1095 a single method call.
1097 "invalidArguments": Returned if one of the arguments is of the wrong
1098 type, or otherwise invalid. A "description" property MAY be present
1099 on the response object to help debug with an explanation of what the
1100 problem was.
1102 3.10.2. getFooUpdates
1104 When the state of the set of Foo records changes on the server
1105 (whether due to creation, updates or deletion), the _state_ property
1106 of the _foos_ response will change. The _getFooUpdates_ call allows
1107 a client to efficiently update the state of any its Foo cache to
1108 match the new state on the server. It takes the following arguments:
1110 o *accountId*: "String|null" The id of the Account to use. If
1111 "null", the primary account is used.
1113 o *sinceState*: "String" The current state of the client. This is
1114 the string that was returned as the _state_ argument in the _foos_
1115 response. The server will return the changes made since this
1116 state.
1118 o *maxChanges*: "Number|null" The maximum number of Foo ids to
1119 return in the response. The server MAY choose to return fewer
1120 than this value, but MUST NOT return more. If not given by the
1121 client, the server may choose how many to return. If supplied by
1122 the client, the value MUST be a positive integer greater than 0.
1123 If a value outside of this range is given, the server MUST reject
1124 the call with an "invalidArguments" error.
1126 o *fetchRecords*: "Boolean|null" If "true", immediately after
1127 outputting the _fooUpdates_ response, the server will make an
1128 implicit call to _getFoos_ with the _changed_ property of the
1129 response as the _ids_ argument. If "false" or "null", no implicit
1130 call will be made.
1132 o *fetchRecordProperties*: "String[]|null" If the _getFoos_ method
1133 takes a _properties_ argument, this argument is passed through on
1134 implicit calls (see the _fetchRecords_ argument).
1136 The response to _getFooUpdates_ is called _fooUpdates_. It has the
1137 following arguments:
1139 o *accountId*: "String" The id of the account used for the call.
1141 o *oldState*: "String" This is the _sinceState_ argument echoed
1142 back; the state from which the server is returning changes.
1144 o *newState*: "String" This is the state the client will be in after
1145 applying the set of changes to the old state.
1147 o *hasMoreUpdates*: "Boolean" If "true", the client may call
1148 _getFooUpdates_ again with the _newState_ returned to get further
1149 updates. If "false", _newState_ is the current server state.
1151 o *changed*: "String[]" An array of Foo ids for records which have
1152 been created or changed but not destroyed since the oldState.
1154 o *removed*: "String[]" An array of Foo ids for records which have
1155 been destroyed since the old state.
1157 The _maxChanges_ argument (and _hasMoreUpdates_ response argument) is
1158 available for data types with potentially large amounts of data (i.e.
1159 those for which there is a _getFooList_ method available for loading
1160 the data in pages). If a _maxChanges_ is supplied, or set
1161 automatically by the server, the server must try to limit the number
1162 of ids across _changed_ and _removed_ to the number given. If there
1163 are more changes than this between the client's state and the current
1164 server state, the update returned MUST take the client to an
1165 intermediate state, from which the client can continue to call
1166 _getFooUpdates_ until it is fully up to date. The server MUST NOT
1167 return more ids than the _maxChanges_ total. If the server is unable
1168 to calculate a suitable intermediate state, it MUST return a
1169 "cannotCalculateChanges" error.
1171 If a Foo record has been modified AND deleted since the oldState, the
1172 server SHOULD just return the id in the _removed_ response, but MAY
1173 return it in the changed response as well. If a Foo record has been
1174 created AND deleted since the oldState, the server SHOULD remove the
1175 Foo id from the response entirely, but MAY include it in the
1176 _removed_ response.
1178 The following errors may be returned instead of the _fooUpdates_
1179 response:
1181 "accountNotFound": Returned if an _accountId_ was explicitly included
1182 with the request, but it does not correspond to a valid account.
1184 "accountNotSupportedByMethod": Returned if the _accountId_ given
1185 corresponds to a valid account, but the account does not support this
1186 data type.
1188 "invalidArguments": Returned if the request does not include one of
1189 the required arguments, or one of the arguments is of the wrong type,
1190 or otherwise invalid. A _description_ property MAY be present on the
1191 response object to help debug with an explanation of what the problem
1192 was.
1194 "cannotCalculateChanges": Returned if the server cannot calculate the
1195 changes from the state string given by the client. Usually due to
1196 the client's state being too old, or the server being unable to
1197 produce an update to an intermediate state when there are too many
1198 updates. The client MUST invalidate its Foo cache.
1200 3.10.3. setFoos
1202 Modifying the state of Foo objects on the server is done via the
1203 _setFoos_ method. This encompasses creating, updating and destroying
1204 Foo records. This has two benefits:
1206 1. It allows the server to sort out ordering and dependencies that
1207 may exist if doing multiple operations at once (for example to
1208 ensure there is always a minimum number of a certain record
1209 type).
1211 2. A single call can make all the changes you want to a particular
1212 type. If the client wants to use _ifInState_ to guard its
1213 changes, it is only possible for it to make one call that
1214 modifies any particular type per request, since it will need the
1215 new state following that call to make the next modification.
1217 The _setFoos_ method takes the following arguments:
1219 o *accountId*: "String|null" The id of the Account to use. If
1220 "null", the primary account is used.
1222 o *ifInState*: "String|null" This is a state string as returned by
1223 the _getFoos_ method. If supplied, the string must match the
1224 current state, otherwise the method will be aborted and a
1225 "stateMismatch" error returned. If "null", any changes will be
1226 applied to the current state.
1228 o *create*: "String[Foo]|null" A map of _creation id_ (an arbitrary
1229 string set by the client) to Foo objects (containing all
1230 properties except the id, unless otherwise stated in the specific
1231 documentation of the data type). If "null", no objects will be
1232 created.
1234 o *update*: "String[Foo]|null" A map of id to Foo objects. The
1235 object may omit any property; only properties that have changed
1236 need be included. If "null", no objects will be updated.
1238 o *destroy*: "String[]|null" A list of ids for Foo objects to
1239 permanently delete. If "null", no objects will be deleted.
1241 Each create, update or destroy is considered an atomic unit. It is
1242 permissible for the server to commit some of the changes but not
1243 others, however it is not permissible to only commit part of an
1244 update to a single record (e.g. update a _name_ property but not a
1245 _count_ property, if both are supplied in the update object).
1247 If a create, update or destroy is rejected, the appropriate error
1248 MUST be added to the notCreated/notUpdated/notDestroyed property of
1249 the response and the server MUST continue to the next create/update/
1250 destroy. It does not terminate the method.
1252 If an id given cannot be found, the update or destroy MUST be
1253 rejected with a "notFound" set error.
1255 Some record objects may hold references to others (foreign keys).
1256 When records are created or modified, they may reference other
1257 records being created _in the same API request_ by using the creation
1258 id prefixed with a "#". The order of the method calls in the request
1259 by the client MUST be such that the record being referenced is
1260 created in the same or an earlier call. The server thus never has to
1261 look ahead. Instead, while processing a request (a series of method
1262 calls), the server MUST keep a simple map for the duration of the
1263 request of creation id to record id for each newly created record, so
1264 it can substitute in the correct value if necessary in later method
1265 calls. The type
1267 Creation ids are scoped by type; a separate "creation id -> id" map
1268 MUST be kept for each type. Foreign key references are always for a
1269 particular record type, so use of the same creation key in two
1270 different types cannot cause any ambiguity. Creation ids sent by the
1271 client SHOULD be unique within the single API request for a
1272 particular data type. If a creation id is reused for the same type,
1273 the server MUST map the creation id to the most recently created item
1274 with that id.
1276 The response to _setFoos_ is called _foosSet_. It has the following
1277 arguments:
1279 o *accountId*: "String" The id of the account used for the call.
1281 o *oldState*: "String|null" The state string that would have been
1282 returned by _getFoos_ before making the requested changes, or
1283 "null" if the server doesn't know what the previous state string
1284 was.
1286 o *newState*: "String" The state string that will now be returned by
1287 _getFoos_.
1289 o *created*: "String[Foo]" A map of the creation id to an object
1290 containing any *server-assigned* properties of the Foo object
1291 (including the id) for all successfully created records.
1293 o *updated*: "String[Foo|null]" The _keys_ in this map are the ids
1294 of all Foos that were successfully updated. Some data types may
1295 have properties which can only be determined by the server, and
1296 which may change as a result of the other properties being updated
1297 by the client. In this case, the _value_ for the corresponding id
1298 in the map is an object containing the updated value of each
1299 property the *server changed* on the record. Otherwise (if no
1300 properties changed on the server other than those explicitly
1301 updated by the client), the value is "null".
1303 o *destroyed*: "String[]" A list of Foo ids for records that were
1304 successfully destroyed.
1306 o *notCreated*: "String[SetError]" A map of creation id to a
1307 SetError object for each record that failed to be created. The
1308 possible errors are defined in the description of the method for
1309 specific data types.
1311 o *notUpdated*: "String[SetError]" A map of Foo id to a SetError
1312 object for each record that failed to be updated. The possible
1313 errors are defined in the description of the method for specific
1314 data types.
1316 o *notDestroyed*: "String[SetError]" A map of Foo id to a SetError
1317 object for each record that failed to be destroyed. The possible
1318 errors are defined in the description of the method for specific
1319 data types.
1321 A *SetError* object has the following properties:
1323 o *type*: "String" The type of error.
1325 o *description*: "String|null" A description of the error to display
1326 to the user.
1328 Other properties may also be present on the object, as described in
1329 the relevant methods.
1331 The following errors may be returned instead of the "foosSet"
1332 response:
1334 "accountNotFound": Returned if an _accountId_ was explicitly included
1335 with the request, but it does not correspond to a valid account.
1337 "accountNotSupportedByMethod": Returned if the _accountId_ given
1338 corresponds to a valid account, but the account does not support this
1339 data type.
1341 "accountReadOnly": Returned if the account has isReadOnly == true.
1343 "requestTooLarge": Returned if the total number of objects to create,
1344 update or destroy exceeds the maximum number the server is willing to
1345 process in a single method call.
1347 "invalidArguments": Returned if one of the arguments is of the wrong
1348 type, or otherwise invalid. A "description" property MAY be present
1349 on the response object to help debug with an explanation of what the
1350 problem was.
1352 "stateMismatch": Returned if an "ifInState" argument was supplied and
1353 it does not match the current state.
1355 3.11. Querying data
1357 For data sets where the total amount of data is expected to be very
1358 small, clients can just fetch the complete set of data and then do
1359 any sorting/filtering locally. However, for large data sets (e.g.
1360 multi-gigabyte mailboxes), the client needs to be able to perform a
1361 query on the server for the data type.
1363 3.11.1. getFooList
1365 A query on the set of Foos in an account is made by calling
1366 _getFooList_. This takes a number of arguments to determine which
1367 records to include, how they should be sorted, and which part of the
1368 result should be returned (the full list may be _very_ long). The
1369 result is returned as a list of Foo ids. Optionally, the records
1370 themselves may be fetched at the same time.
1372 A call to _getFooList_ takes the following arguments:
1374 o *filter*: "FilterCondition" Determines the set of Foos returned in
1375 the results. This is an "object", whose allowed properties and
1376 semantics depend on the data type.
1378 o *sort*: "String[]|null" Lists the properties to compare between
1379 two Foo records to determine which comes first in the sort. If
1380 two Foo records have an identical value for the first property,
1381 the next property will be considered and so on. If all properties
1382 are the same (this includes the case where an empty array or
1383 "null" is given as the _sort_ argument), the sort order is server-
1384 dependent, but MUST be stable between calls to "getFooList".
1385 Following each property name there MUST be a space and then either
1386 the string "asc" or "desc" to specify ascending or descending sort
1387 for that property. e.g. "[ "date desc", "name asc" ]"
1389 o *position*: "Number|null" The 0-based index of the first id in the
1390 full list of results to return, presumed "0" if "null". If a
1391 negative value is given, the call MUST be rejected with an
1392 "invalidArguments" error.
1394 o *limit*: "Number|null" The maximum number of results to return.
1395 If "null", no limit presumed. The server MAY choose to enforce a
1396 maximum "limit" argument. In this case, if a greater value is
1397 given (or if it is "null"), the limit should be clamped to the
1398 maximum; since the total number of results in the list is
1399 returned, the client can determine if it has received all the
1400 results. If a negative value is given, the call MUST be rejected
1401 with an "invalidArguments" error.
1403 o *fetchFoos*: "Boolean|null" If "true" then after outputting a
1404 _fooList_ response, an implicit call will be made to _getFoos_
1405 with the "fooIds" array in the response as the _ids_ argument. If
1406 "false" or "null", no implicit call will be made.
1408 o *fetchFooProperties*: "String[]|null" The list of properties to
1409 fetch on any fetched foos. See _getFoos_ for a full description.
1411 The response to a call to _getFooList_ is called _fooList_. It has
1412 the following arguments:
1414 o *filter*: "FilterCondition" The filter of the foo list. Echoed
1415 back from the call.
1417 o *sort*: "String[]|null" A list of Foo property names used to sort
1418 by. Echoed back from the call.
1420 o *state*: "String" A string encoding the current state on the
1421 server. This string will change if the results of the Foo list
1422 MAY have changed (for example, there has been a change to the
1423 state of the set of Foos; it does not guarantee that anything in
1424 the list has changed). It may be passed to _getFooListUpdates_ to
1425 efficiently get the set of changes from the client's current
1426 state. Should a client receive back a response with a different
1427 state string to a previous call, it MUST either throw away the
1428 currently cached list and fetch it again (note, this does not
1429 require fetching the foos again, just the list of ids) or, call
1430 _getFooListUpdates_ to get the delta difference.
1432 o *canCalculateUpdates*: "Boolean" This is "true" if the server
1433 supports calling _getFooListUpdates_ with these "filter"/"sort"
1434 parameters. Note, this does not guarantee that the
1435 _getFooListUpdates_ call will succeed, as it may only be possible
1436 for a limited time afterwards due to server internal
1437 implementation details.
1439 o *position*: "Number" The 0-based index of the first result in the
1440 "fooIds" array within the complete list of results.
1442 o *total*: "Number" The total number of foos in the foos list (given
1443 the _filter_).
1445 o *fooIds*: "String[]" The list of Foo ids for each foo in the list
1446 after filtering and sorting, starting at the index given by the
1447 _position_ argument of this response, and continuing until it hits
1448 the end of the list or reaches the "limit" number of ids.
1450 The following errors may be returned instead of the "fooList"
1451 response:
1453 "accountNotFound": Returned if an _accountId_ was explicitly included
1454 with the request, but it does not correspond to a valid account.
1456 "accountNotSupportedByMethod": Returned if the _accountId_ given
1457 corresponds to a valid account, but the account does not support this
1458 data type.
1460 "invalidArguments": Returned if the request does not include one of
1461 the required arguments, or one of the arguments is of the wrong type,
1462 or otherwise invalid. A "description" property MAY be present on the
1463 response object to help debug with an explanation of what the problem
1464 was.
1466 3.11.2. getFooListUpdates
1468 The "getFooListUpdates" call allows a client to efficiently update
1469 the state of any cached foo list to match the new state on the
1470 server. It takes the following arguments:
1472 o *filter*: "FilterCondition" The filter argument that was used with
1473 _getFooList_.
1475 o *sort*: "String[]|null" The sort argument that was used with
1476 _getFooList_.
1478 o *sinceState*: "String" The current state of the client. This is
1479 the string that was returned as the _state_ argument in the
1480 _fooList_ response. The server will return the changes made since
1481 this state.
1483 o *maxChanges*: "Number|null" The maximum number of changes to
1484 return in the response. See below for a more detailed
1485 description.
1487 The response to _getFooListUpdates_ is called _fooListUpdates_ It has
1488 the following arguments:
1490 o *filter*: "FilterCondition" The filter of the foo list. Echoed
1491 back from the call.
1493 o *sort*: "String[]|null" A list of Foo property names used to sort
1494 by. Echoed back from the call.
1496 o *oldState*: "String" This is the "sinceState" argument echoed
1497 back; the state from which the server is returning changes.
1499 o *newState*: "String" This is the state the client will be in after
1500 applying the set of changes to the old state.
1502 o *total*: "Number" The total number of foos in the current foo list
1503 (given the _filter_).
1505 o *removed*: "String[]" The _fooId_ for every foo that was in the
1506 list in the old state and is not in the list in the new state. If
1507 the server cannot calculate this exactly, the server MAY return
1508 extra foos in addition that MAY have been in the old list but are
1509 not in the new list. If the _filter_ or _sort_ includes a mutable
1510 property, the server MUST include all foos in the current list for
1511 which this property MAY have changed.
1513 o *added*: "AddedItem[]" The fooId and index in the list (in the new
1514 state) for every foo that has been added to the list since the old
1515 state AND every foo in the current list that was included in the
1516 _removed_ array (due to a filter or sort based upon a mutable
1517 property). The array MUST be sorted in order of index, lowest
1518 index first.
1520 An *AddedItem* object has the following properties:
1522 o *fooId*: "String"
1524 o *index*: "Number"
1526 The result of this should be that if the client has a cached sparse
1527 array of foo ids in the list in the old state:
1529 fooIds = [ "id1", "id2", null, null, "id3", "id4", null, null, null ]
1531 then if it *splices out* all foos in the removed array:
1533 removed = [ "id2", ... ];
1534 fooIds => [ "id1", null, null, "id3", "id4", null, null, null ]
1536 and *splices in* (in order) all of the foos in the added array:
1538 added = [{ fooId: "id5", index: 0, ... }];
1539 fooIds => [ "id5", "id1", null, null, "id3", "id4", null, null, null ]
1541 then the foo list will now be in the new state.
1543 The following errors may be returned instead of the "fooListUpdates"
1544 response:
1546 "accountNotFound": Returned if an _accountId_ was explicitly included
1547 with the request, but it does not correspond to a valid account.
1549 "accountNotSupportedByMethod": Returned if the _accountId_ given
1550 corresponds to a valid account, but the account does not support this
1551 data type.
1553 "invalidArguments": Returned if the request does not include one of
1554 the required arguments, or one of the arguments is of the wrong type,
1555 or otherwise invalid. A _description_ property MAY be present on the
1556 response object to help debug with an explanation of what the problem
1557 was.
1559 "tooManyChanges": Returned if there are more changes the the client's
1560 _maxChanges_ argument. Each item in the removed or added array is
1561 considered as one change. The client may retry with a higher max
1562 changes or invalidate its cache of the foo list.
1564 "cannotCalculateChanges": Returned if the server cannot calculate the
1565 changes from the state string given by the client. Usually due to
1566 the client's state being too old. The client MUST invalidate its
1567 cache of the foo list.
1569 4. Downloading binary data
1571 Binary data is referenced by a _blobId_ in JMAP. A blob id does not
1572 have a name inherent to it, but this is normally given in the same
1573 object that contains the blob id.
1575 After completing authentication, the client will receive a
1576 _downloadUrl_ as part of the response. This is in [RFC6570] URI
1577 Template (level 1) format. The URL MUST contain variables called
1578 "accountId" and "blobId". The URL SHOULD contain a variable called
1579 "name".
1581 The client may use this template in combination with an accountId and
1582 blobId to download any binary data (files) referenced by other
1583 objects. Since a blob is not associated with a particular name, the
1584 template SHOULD allow a name to be substituted in as well; the server
1585 will return this as the filename if it sets a "Content-Disposition"
1586 header.
1588 To download the data the client MUST make an authenticated GET
1589 request to the download URL with the appropriate variables
1590 substituted in, and then follow any redirects. The client SHOULD
1591 send an "Accept" header with the content type they would like the
1592 server to return for the file.
1594 In situations where it's not easy to authenticate the download
1595 request (e.g.: when downloading a file through a link in a HTML
1596 document), the client MAY use a signed GET request (see the
1597 authentication chapter for how to issue a signed request). Instead
1598 of specifying an "Accept" header, the client SHOULD add an "accept"
1599 query parameter to the signed URL, with the value being the content
1600 type to use for the response.
1602 After following redirects, the server MUST return one of the
1603 following responses to a request to the download URL:
1605 4.1. 200: OK
1607 Request successful. The binary data is returned. The "Content-Type"
1608 header SHOULD be set to the type as requested in the "Accept" header
1609 by the client, or "application/octet-stream" if unknown and no
1610 "Accept" header given.
1612 4.2. 401: Unauthorized
1614 The "Authorization" header was missing or did not contain a valid
1615 token and there was no "access_token" query parameter, or it did not
1616 contain a valid token. Reauthenticate and then retry the request.
1617 As per the HTTP spec, the response MUST have a "WWW-Authenticate"
1618 header listing the available authentication schemes.
1620 The server MAY return an HTML page response, which clients MAY show
1621 to the user. This is primarily for when the URL is passed off to the
1622 browser, and the JMAP client may not see the actual response.
1624 4.3. 404: Not Found
1626 The file was not found at this address.
1628 4.4. 503: Service Unavailable
1630 The server is currently down. The client should try again later with
1631 exponential backoff. There is no content in the response.
1633 5. Uploading binary data
1635 There is a single endpoint which handles all file uploads, regardless
1636 of what they are to be used for. To upload a file, the client
1637 submits a POST request to the file upload endpoint (see the
1638 authentication section for information on how to obtain this URL).
1639 The Content-Type MUST be correctly set for the type of the file being
1640 uploaded. The request MUST be authenticated as per any HTTP request.
1641 The request MAY include an "X-JMAP-AccountId" header, with the value
1642 being the account to use for the request. Otherwise, the default
1643 account will be used.
1645 The server will respond with one of the following HTTP response
1646 codes:
1648 5.1. 201: File uploaded successfully
1650 The content of the response is a single JSON object with the
1651 following properties:
1653 o *accountId*: "String" The id of the account used for the call.
1655 o *blobId*: "String", The id representing the binary data uploaded.
1656 The data for this id is immutable. The id _only_ refers to the
1657 binary data, not any metadata.
1659 o *type*: "String" The content type of the file.
1661 o *size*: "Number" The size of the file in bytes.
1663 o *expires*: "Date" The date the file will be deleted from temporary
1664 storage if not referenced by another object, e.g. used in a draft.
1666 Once the file has been used, for example attached to a draft message,
1667 the file will no longer expire, and is instead guaranteed to exist
1668 while at least one other object references it. Once no other object
1669 references it, the server MAY immediately delete the file at any
1670 time. It MUST NOT delete the file during the method call which
1671 removed the last reference, so that if there is a create and a delete
1672 within the same call that both reference the file, this always works.
1674 If uploading a file would take the user over quota, the server SHOULD
1675 delete previously uploaded (but unused) files before their expiry
1676 time. This means a client does not have to explicitly delete unused
1677 temporary files (indeed, there is no way for it to do so).
1679 If identical binary content is uploaded, the same _blobId_ SHOULD be
1680 returned.
1682 The server MUST return one of the following responses to a request to
1683 the upload URL:
1685 5.2. 400: Bad request
1687 The request was malformed (this includes the case where an "X-JMAP-
1688 AccountId" header is sent with a value that does not exist). The
1689 client SHOULD NOT retry the same request. There is no content in the
1690 response.
1692 5.3. 401: Unauthorized
1694 The "Authorization" header was missing or did not contain a valid
1695 token. Reauthenticate and then retry the request. As per the HTTP
1696 spec, the response MUST have a "WWW-Authenticate" header listing the
1697 available authentication schemes. There is no content in the
1698 response.
1700 5.4. 404: Not Found
1702 The upload endpoint has moved. See the Authentication section of the
1703 spec for how to rediscover the current URL to use. There is no
1704 content in the response.
1706 5.5. 413: Request Entity Too Large
1708 The file is larger than the maximum size the server is willing to
1709 accept for a single file. The client SHOULD NOT retry uploading the
1710 same file. There is no content in the response. The client may
1711 discover the maximum size the server is prepared to accept by
1712 inspecting the server _capabilities_ object, returned with the
1713 successful authentication response.
1715 5.6. 415: Unsupported Media Type
1717 The server MAY choose to not allow certain content types to be
1718 uploaded, such as executable files. This error response is returned
1719 if an unacceptable type is uploaded. The client SHOULD NOT retry
1720 uploading the same file. There is no content in the response.
1722 5.6.1. 429: Rate limited
1724 Returned if the client has made too many upload requests recently, or
1725 has too many concurrent uploads currently in progress. Clients
1726 SHOULD wait a while then try again. The response MAY include a
1727 "Retry-After" header indicating how long to wait before making a new
1728 request.
1730 5.7. 503: Service Unavailable
1732 The server is currently down. The client should try again later with
1733 exponential backoff. There is no content in the response.
1735 6. Push
1737 Any modern email client should be able to update instantly whenever
1738 the data on the server is changed by another client or message
1739 delivery. Push notifications in JMAP occur out-of-band (i.e. not
1740 over the same connection as API exchanges) so that they can make use
1741 of efficient native push mechanisms on different platforms.
1743 The general model for push is simple and does not send any sensitive
1744 data over the push channel, making it suitable for use with less
1745 trusted 3rd party intermediaries. The format allows multiple changes
1746 to be coalesced into a single push update, and the frequency of
1747 pushes to be rate limited by the server. It doesn't matter if some
1748 push events are dropped before they reach the client; it will still
1749 get all changes next time it syncs.
1751 When something changes on the server, the server pushes a small JSON
1752 object to the client with the following property:
1754 o *changed*: "String[ChangedStates]" A map of _account id_ to an
1755 object encoding the state of data types which have changed for
1756 that account since the last push event, for each of the accounts
1757 to which the user has access and for which something has changed.
1759 A *ChangedStates* object is a map. The keys are the plural type name
1760 "Foos" (e.g. "Mailboxes" or "Messages"), and the value is the
1761 _state_ property that would currently be returned by a call to
1762 _getFoos_.
1764 Upon receiving this data, the client can compare the new state
1765 strings with its current values to see whether it has the current
1766 data for these types. The actual changes can then be efficiently
1767 fetched in a single standard API request (using the _getFooUpdates_
1768 type methods).
1770 6.1. Event Source
1772 There are two mechanisms by which the client can receive the push
1773 events. The first is directly via a "text/event-stream" resource, as
1774 described in . This is
1775 essentially a long running HTTP request down which the server can
1776 push data. When a change occurs, the server MUST push an event
1777 called *state* to any connected clients.
1779 The server MAY also set a new "Last-Event-Id" that encodes the entire
1780 server state visible to the user. When a new connection is made to
1781 the event-source endpoint, the server can then work out whether the
1782 client has missed some changes which it should send immediately.
1784 The server MUST also send an event called *ping* with an empty object
1785 as the data if a maximum of 5 minutes has elapsed since the previous
1786 event. This MUST NOT set a new "Last-Event-Id". A client may detect
1787 the absence of these to determine that the HTTP connection has been
1788 dropped somewhere along the route and so it needs to re-establish the
1789 connection.
1791 Refer to the Authentication section of this spec for details on how
1792 to get the URL for the event-source endpoint. The request must be
1793 authenticated using an "Authorization" header like any HTTP request.
1795 A client MAY hold open multiple connections to the event-source,
1796 although it SHOULD try to use a single connection for efficiency.
1798 6.2. Web hook
1800 The second push mechanism is to register a callback URL to which the
1801 JMAP server will make an HTTPS POST request whenever the event
1802 occurs. The request MUST have a content type of "application/json"
1803 and contain the same UTF-8 JSON encoded object as described above as
1804 the body.
1806 The JMAP server MUST also set the following headers in the POST
1807 request: - "X-JMAP-EventType: state" - "X-JMAP-User: ${username}"
1808 where "${username}" is the username of the authenticated user for
1809 which the push event occurred.
1811 The JMAP server MUST follow any redirects. If the final response
1812 code from the server is "2xx", the callback is considered a success.
1813 If the response code is "503" (Service Unavailable), the JMAP server
1814 MAY try again later (but may also just drop the event). If the
1815 response code is "429" (Too Many Requests) the JMAP server SHOULD
1816 attempt to reduce the frequency of pushes to that URL. Any other
1817 response code MUST be considered a *permanent failure* and the
1818 callback should be deregistered (not tried again even for future
1819 events unless explicitly re-registered by the client).
1821 The URL set by the client MUST use the HTTPS protocol and SHOULD
1822 encode within it a unique token that can be verified by the server to
1823 know that the request comes from the JMAP server the authenticated
1824 client connected to.
1826 The callback is tied to the access token used to create it. Should
1827 the access token expire or be revoked, the callback MUST be removed
1828 by the JMAP server. The client MUST re-register the callback after
1829 reauthenticating to resume callbacks.
1831 Each session may only have a single callback URL registered. It can
1832 be set or retrieved using the following API calls.
1834 6.2.1. setPushCallback
1836 To set the web hook, make a call to _setPushCallback_. It takes the
1837 following argument:
1839 o *callback*: "String|null" The (HTTPS) URL the JMAP server should
1840 POST events to. This will replace any previously set URL. Set to
1841 "null" to just remove any previously set callback URL.
1843 The response to _setPushCallback_ is called _pushCallbackSet_. It has
1844 the following argument:
1846 o *callback*: "String|null" Echoed back from the call.
1848 The following error may be returned instead of the _mailboxesSet_
1849 response:
1851 "invalidUrl": Returned if the URL does not begin with "https://", or
1852 is otherwise syntactically invalid or does not resolve.
1854 6.2.2. getPushCallback
1856 To check the currently set callback URL (if any), make a call to
1857 _getPushCallback_. It does not take any arguments. The response to
1858 _getPushCallback_ is called "pushCallback". It has a single
1859 argument:
1861 o *callback*: "String|null" The URL the JMAP server is currently
1862 posting push events to, or "null" if none.
1864 7. References
1866 7.1. Normative References
1868 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1869 Requirement Levels", BCP 14, RFC 2119,
1870 DOI 10.17487/RFC2119, March 1997,
1871 .
1873 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
1874 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
1875 .
1877 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
1878 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
1879 2003, .
1881 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
1882 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
1883 .
1885 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
1886 Uniform Resource Identifiers (URIs)", RFC 5785,
1887 DOI 10.17487/RFC5785, April 2010,
1888 .
1890 [RFC6186] Daboo, C., "Use of SRV Records for Locating Email
1891 Submission/Access Services", RFC 6186,
1892 DOI 10.17487/RFC6186, March 2011,
1893 .
1895 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
1896 and D. Orchard, "URI Template", RFC 6570,
1897 DOI 10.17487/RFC6570, March 2012,
1898 .
1900 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
1901 Framework: Bearer Token Usage", RFC 6750,
1902 DOI 10.17487/RFC6750, October 2012,
1903 .
1905 [RFC6764] Daboo, C., "Locating Services for Calendaring Extensions
1906 to WebDAV (CalDAV) and vCard Extensions to WebDAV
1907 (CardDAV)", RFC 6764, DOI 10.17487/RFC6764, February 2013,
1908 .
1910 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
1911 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
1912 2014, .
1914 [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493,
1915 DOI 10.17487/RFC7493, March 2015,
1916 .
1918 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
1919 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
1920 .
1922 7.2. URIs
1924 [1] https://tools.ietf.org/html/rfc6238
1926 [2] https://developers.yubico.com/OTP/
1928 [3] https://fidoalliance.org/specifications/download/
1930 [4] https://tools.ietf.org/html/rfc7519
1932 [5] https://tools.ietf.org/html/rfc7519
1934 [6] https://jwt.io/
1936 Author's Address
1938 Neil Jenkins
1939 FastMail
1940 Level 1, 91 William St
1941 Melbourne VIC 3000
1942 Australia
1944 Email: neilj@fastmail.com
1945 URI: https://www.fastmail.com