description:The unix timestamp at which the association was verified.
description:The unix timestamp at which the association was verified.
signatures:
signatures:
type:object
type:object
description:The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.
description:|-
The signatures of the verifying identity services which show that the
association should be trusted, if you trust the verifying identity
# Licensed under the Apache License, Version 2.0 (the "License");
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# you may not use this file except in compliance with the License.
@ -20,8 +21,9 @@ info:
host:localhost:8090
host:localhost:8090
schemes:
schemes:
- https
- https
- http
basePath:/_matrix/identity/api/v1
basePath:/_matrix/identity/api/v1
consumes:
- application/json
produces:
produces:
- application/json
- application/json
paths:
paths:
@ -46,7 +48,7 @@ paths:
responses:
responses:
200:
200:
description:
description:
The association for that 3pid, or the empty object if no association is known.
The association for that 3pid, or an empty object if no association is known.
examples:
examples:
application/json:{
application/json:{
"address": "louise@bobs.burgers",
"address": "louise@bobs.burgers",
@ -66,10 +68,10 @@ paths:
properties:
properties:
address:
address:
type:string
type:string
description:The 3pid address of the user being looked up.
description:The 3pid address of the user being looked up, matching the address requested.
medium:
medium:
type:string
type:string
description:The literal string "email".
description:A medium from the `3PID Types`_ Appendix, matching the medium requested.
mxid:
mxid:
type:string
type:string
description:The Matrix user ID associated with the 3pid.
description:The Matrix user ID associated with the 3pid.
@ -126,7 +128,9 @@ paths:
#- type: 3PID Address
#- type: 3PID Address
- type:string
- type:string
- type:string
- type:string
description:an array of arrays containing the `3PID Types`_ with the ``medium`` in first position and the ``address`` in second position.
description:|-
An array of arrays containing the `3PID Types`_ with the ``medium``
in first position and the ``address`` in second position.
required:
required:
- "threepids"
- "threepids"
responses:
responses:
@ -157,6 +161,9 @@ paths:
- type:string
- type:string
- type:string
- type:string
- type:string
- type:string
description:an array of array containing the `3PID Types`_ with the ``medium`` in first position, the ``address`` in second position and Matrix ID in third position.
description:|-
An array of array containing the `3PID Types`_ with the ``medium``
in first position, the ``address`` in second position and Matrix user
An identity service has some long-term public-private keypairs. These are named
An identity service has some long-term public-private keypairs. These are named
in a scheme ``algorithm:identifier``, e.g. ``ed25519:0``. When signing an
in a scheme ``algorithm:identifier``, e.g. ``ed25519:0``. When signing an
association, the Matrix standard JSON signing format is used, as specified in
association, the standard `Signing JSON`_ algorithm applies.
the server-server API specification under the heading "Signing Events".
In the event of key compromise, the identity service may revoke any of its keys.
In the event of key compromise, the identity service may revoke any of its keys.
An HTTP API is offered to get public keys, and check whether a particular key is
An HTTP API is offered to get public keys, and check whether a particular key is
valid.
valid.
The identity server may also keep track of some short-term public-private
The identity service may also keep track of some short-term public-private
keypairs, which may have different usage and lifetime characteristics than the
keypairs, which may have different usage and lifetime characteristics than the
service's long-term keys.
service's long-term keys.
{{pubkey_is_http_api}}
{{pubkey_is_http_api}}
Association Lookup
Association lookup
------------------
------------------
{{lookup_is_http_api}}
{{lookup_is_http_api}}
Establishing Associations
Establishing associations
-------------------------
-------------------------
The flow for creating an association is session-based.
The flow for creating an association is session-based.
@ -183,6 +213,12 @@ 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
attempts to perform these actions after the expiry will be rejected, and a new
session should be created and used instead.
session should be created and used instead.
To start a session, the client makes a request to the appropriate ``/requestToken``
endpoint. The user then receives a validation token which should be provided
to the client. The client then provides the token to the appropriate ``/submitToken``
endpoint, completing the session. At this point, the client should ``/bind`` the
third party identifier or leave it for another entity to bind.
Email associations
Email associations
~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~
@ -198,53 +234,31 @@ General
{{associations_is_http_api}}
{{associations_is_http_api}}
Invitation Storage
Invitation storage
------------------
------------------
An identity service can store pending invitations to a user's 3pid, which will
An identity service can store pending invitations to a user's 3pid, which will
be retrieved and can be either notified on or look up when the 3pid is
be retrieved and can be either notified on or look up when the 3pid is
associated with a Matrix user ID.
associated with a Matrix user ID.
At a later point, if the owner of that particular 3pid binds it with a Matrix user ID, the identity server will attempt to make an HTTP POST to the Matrix user's homeserver which looks roughly as below::
At a later point, if the owner of that particular 3pid binds it with a Matrix user
ID, the identity service will attempt to make an HTTP POST to the Matrix user's
POST https://bar.com:8448/_matrix/federation/v1/3pid/onbind
homeserver via the `/3pid/onbind`_ endpoint. The request MUST be signed with a
Content-Type: application/json
long-term private key for the identity service.
{
"medium": "email",
"address": "foo@bar.baz",
"mxid": "@alice:example.tld",
"invites": [
{
"medium": "email",
"address": "foo@bar.baz",
"mxid": "@alice:example.tld",
"room_id": "!something:example.tld",
"sender": "@bob:example.tld",
"signed": {
"mxid": "@alice:example.tld",
"signatures": {
"vector.im": {
"ed25519:0": "somesignature"
}
},
"token": "sometoken"
}
}
]
}
Where the signature is produced using a long-term private key.
{{store_invite_is_http_api}}
{{store_invite_is_http_api}}
Ephemeral invitation signing
Ephemeral invitation signing
----------------------------
----------------------------
To aid clients who may not be able to perform crypto themselves, the identity service offers some crypto functionality to help in accepting invitations.
To aid clients who may not be able to perform crypto themselves, the identity
This is less secure than the client doing it itself, but may be useful where this isn't possible.
service offers some crypto functionality to help in accepting invitations.
This is less secure than the client doing it itself, but may be useful where
Travis Ralston
6 years ago