Notes on the format of IS session IDs and tokens

api/identity/definitions/sid.yaml

@@ -15,6 +15,10 @@ type: object
 properties:
   sid:
     type: string
-    description: The session ID.
+    description: |
+      The session ID. Session IDs are opaque strings generated by the identity
+      service. They must consist entirely of the characters
+      ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255 characters and they
+      must not be empty.
     example: "123abc"
 required: ['sid']

api/identity/email_associations.yaml

@@ -81,6 +81,12 @@ paths:
         associate the email address with any Matrix user ID. Specifically,
         calls to ``/lookup`` will not show a binding.
 
+        The identity service is free to match the token case-insensitively, or
+        carry out other mapping operations such as unicode
+        normalisation. Whether to do so is an implementation detail for the
+        identity service. Clients must always pass on the token without
+        modification.
+
         Note: for backwards compatibility with previous drafts of this
         specification, the parameters may also be specified as
         ``application/x-form-www-urlencoded`` data.  However, this usage is

api/identity/phone_associations.yaml

@@ -83,6 +83,12 @@ paths:
         associate the phone number address with any Matrix user
         ID. Specifically, calls to ``/lookup`` will not show a binding.
 
+        The identity service is free to match the token case-insensitively, or
+        carry out other mapping operations such as unicode
+        normalisation. Whether to do so is an implementation detail for the
+        identity service. Clients must always pass on the token without
+        modification.
+
         Note: for backwards compatibility with previous drafts of this
         specification, the parameters may also be specified as
         ``application/x-form-www-urlencoded`` data. However, this usage is

specification/identity_service_api.rst

@@ -217,11 +217,24 @@ session, within a 24 hour period since its most recent modification. Any
 attempts to perform these actions after the expiry will be rejected, and a new
 session should be created and used instead.
 
-To start a session, the client makes a request to the appropriate ``/requestToken``
+To start a session, the client makes a request to the appropriate
-endpoint. The user then receives a validation token which should be provided
+``/requestToken`` endpoint. The identity service then sends a validation token
-to the client. The client then provides the token to the appropriate ``/submitToken``
+to the user, and the user provides the token to the client. The client then
-endpoint, completing the session. At this point, the client should ``/bind`` the
+provides the token to the appropriate ``/submitToken`` endpoint, completing the
-third party identifier or leave it for another entity to bind.
+session. At this point, the client should ``/bind`` the third party identifier
+or leave it for another entity to bind.
+
+Format of a validation token
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The format of the validation token is left up to the identity service: it
+should choose one appropriate to the 3PID type. (For example, it would be
+inappropriate to expect a user to copy a long passphrase including punctuation
+from an SMS message into a client.)
+
+Whatever format the identity service uses, the validation token must consist of
+at most 255 Unicode codepoints. Clients must pass the token through without
+modification.
 
 Email associations
 ~~~~~~~~~~~~~~~~~~