Core Routes: Registration needed

All API endpoints needed for Client-Home Server communication. This Page only includes routes which a client can request from its home server. For routes which can also be accessed from a foreign server, or with no authentication at all, see the Client-Foreign Server API documentation

Unfinished section

TODO: This section is not yet finished. It is missing descriptions for most routes, some error-code responses, etc.

Authorization¶

Bearer token, unless specified otherwise.

Errors¶

The errors listed below are not exhaustive, and only include the most common errors associated with an endpoint. For rate limit errors, see the Rate Limits documentation.

Federated Identity¶

Client-Home Server API endpoints concerned with Federated Identity and managing ID-Certs.

POST Rotate session ID-Cert ¶

/.p2/core/v1/session/idcert

Rotate your keys for a given session. The session_id in the supplied csr must correspond to the session token used in the authorization-Header.

Request¶

Body¶

Type	Description
String, PEM	A new certificate signing request (CSR) with the same session ID

Text Only

mQINBGSDs58BEADCXP1ArorBtOvGnQdAD26gsOMasyLMqnJyUp8XXCdmTx5...

Response¶

201 Created

Contains your new ID-Cert, along with a new session token.

Body¶

Name	Type	Description
`id_cert`	String, PEM	The generated ID-Cert.
`token`	String	An authorization secret, called a "token", valid for this `id_cert`.

JSON

{ 
    "id_cert": "LS0tLS1CRUdJTiBQR1AgUFVCTElDIEtFWS0tLS0tCk1JSUJqRENDQWlNQ0NRRHdFTE1Ba0dBMVVFQ2d3R2FWTnZiV0ZwYm...",
    "token": "Afnaopgi7BXVafjkl34ulvkc..."
}

POST Upload encrypted private key material ¶

/.p2/core/v1/session/keymaterial

Upload encrypted private key material to the server for later retrieval. The upload size must not exceed the server's maximum upload size for this route. This is usually not more than 10kb and can be as low as 800 bytes, depending on the server configuration.

Request¶

Body¶

Array of objects, each containing the following fields:

Name	Type	Description
`key_data`	String, PEM-encoded `PrivateKeyInfo`	The encrypted private key material, PEM-encoded
`serial_number`	String	The serial number of the ID-Cert this key material is associated with.

JSON

[
    {
        "key_data": "LS0tLS1CRUdJTiBQR1AgUFVCTElDIEtFWS0tLS0tCk1JSUJqRENDQWlNQ0NRRHdFTE1Ba0dBMVVFQ2d3R2FWTnZiV0ZwYm...",
        "serial_number": "123456789"
    },
    {
        "key_data": "LS01tLS2aXJUQWlNQ0NRRHdFTE1Ba0dBMVVFQ2d3R2FWTnZiV0ZwYmGa7cadSH9vAVKOMb478bnm43v5VS789...",
        "serial_number": "987654321"
    }
]

Response¶

201 Created404 Not Found409 Conflict413 Request Entity Too Large

Body¶

This response has no body.

Used, if the serial_number does not match any known ID-Cert from this actor.

Body¶

This response has no body.

Status code for when the server already has key material for the given serial_number. The client would need to delete the existing key material before uploading new key material.

Body¶

This response has no body.

Uploaded key material exceeds the server's maximum upload size.

Body¶

This response has no body.

GET Get encrypted private key material ¶

/.p2/core/v1/session/keymaterial

Retrieve encrypted private key material from the server. The serial_numbers, if provided, must match the serial numbers of ID-Certs that the client has uploaded key material for. If no serial_numbers are provided, the server will return all key material that the client has uploaded.

Request¶

Body¶

Type	Description
Array of String	The serial number(s) of the ID-Certs to get key material for.

JSON

["123456789", "987654321"]

Response¶

200 OK204 No Content404 Not Found

Body¶

Array of objects, each containing the following fields:

Name	Type	Description
`key_data`	String, PEM-encoded `PrivateKeyInfo`	The encrypted private key material, PEM-encoded
`serial_number`	String	The serial number of the ID-Cert this key material is associated with.

JSON

[
    {
        "key_data": "LS0tLS1CRUdJTiBQR1AgUFVCTElDIEtFWS0tLS0tCk1JSUJqRENDQWlNQ0NRRHdFTE1Ba0dBMVVFQ2d3R2FWTnZiV0ZwYm...",
        "serial_number": "123456789"
    },
    {
        "key_data": "LS01tLS2aXJUQWlNQ0NRRHdFTE1Ba0dBMVVFQ2d3R2FWTnZiV0ZwYmGa7cadSH9vAVKOMb478bnm43v5VS789...",
        "serial_number": "987654321"
    }
]

Returned, if no serial_numbers are provided and the client has not uploaded any key material.

Body¶

This response has no body.

Returned, if none of the serial_numbers match any known ID-Certs from this actor.

Body¶

This response has no body.

DELETE Delete encrypted private key material ¶

/.p2/core/v1/session/keymaterial

Delete encrypted private key material from the server. The serial_number(s), must match the serial numbers of ID-Certs that the client has uploaded key material for.

Request¶

Body¶

Type	Description
Array of String	The serial number(s) of the ID-Certs to delete key material for.

JSON

["123456789", "987654321"]

Response¶

204 No Content404 Not Found

Body¶

This response has no body.

Returned, if none of the serial_numbers match any known ID-Certs from this actor.

Body¶

This response has no body.

OPTIONS Get encrypted private key material upload size limit¶

/.p2/core/v1/session/keymaterial

Retrieve the maximum upload size for encrypted private key material, in bytes.

Response¶

200 OK

Headers¶

Name	Type	Description
X-Max-Payload-Size	Number	The upload size limit, in bytes.

Body¶

This response has no body.

Services¶

Routes concerned with the "Services" and "Discoverability" sections of the core polyproto specification.

POST Add service to be discovered ¶

/.p2/core/v1/services

Add a service to the list of services discoverable by other actors.

Request¶

Body¶

A singular service object, representing the service that was added.

JSON

{
    "service": "example-service",
    "url": "https://example.com",
    "primary": false
}

Response¶

201 Created409 Conflict

Body¶

An array of at minimum one, and at maximum 2 service objects.

JSON

[
    {
        "service": "example-service",
        "url": "https://example.com",
        "primary": false
    },
    {
        "service": "example-service",
        "url": "https://other.example.com",
        "primary": true
    }
]

The response will contain the updated previous primary service provider, if there was one, along with the new primary service provider.

Returned, if the service and URL combination already exists in the list of discoverable services.

Body¶

This response has no body.

DELETE Delete discoverable service ¶

/.p2/core/v1/services

Remove a service from the list of services discoverable by other actors.

Request¶

Body¶

Name	Type	Description
`url`	String, URL	The base URL of the service to be removed.
`name`	String	The service namespace for which the service is being removed.

JSON

{
    "url": "https://example.com",
    "name": "example-service"
}

Response¶

200 OK404 Not Found

Body¶

Name	Type	Description	Required?
`deleted`	Object, Service	The service that was removed.	Yes
`new_primary`	Object, Service	The new primary service provider, if the removed service was the primary service provider, and there are other service providers available.	No

JSON

{
    "url": "https://example.com"
}

new_primary will be omitted, if the removed service was not the primary service provider or if there are no other service providers available for this service namespace.

Returned, if the service URL does not exist in the list of discoverable services.

Body¶

This response has no body.

PUT Set primary service provider ¶

/.p2/core/v1/services/primary

Set a primary service provider for a given service namespace. This is used to indicate, which service provider should be used by default by other actors, when multiple service providers are available for a given service namespace.

Request¶

Body¶

Name	Type	Description
`url`	String, URL	The base URL of the service to be set as the primary service provider.
`name`	String	The service namespace for which the primary service provider is being set.

JSON

{
    "url": "https://example.com",
    "name": "example-service"
}

Response¶

200 OK

Body¶

An array of at minimum one, and at maximum 2 service objects.

JSON

[
    {
        "service": "example-service",
        "url": "https://example.com",
        "primary": false
    },
    {
        "service": "example-service",
        "url": "https://other.example.com",
        "primary": true
    }
]

The response will contain the updated previous primary service provider, if there was one, along with the new primary service provider.

Migration¶

Routes concerned with identity migration and re-signing messages.

POST Set up a redirect for migrating identities ¶

.p2/core/v1/migration/redirect

POST Request enabling message re-signing (Receive key trial) ¶

.p2/core/v1/migration/messages

POST Complete key trial ¶

.p2/core/v1/migration/messages/keys

TODO: Add routes concerned with account and data migration.

Glossary¶

Actor - An entity represented by a federation ID, registered on a home server. Actors can be users, bots, or any other entity with a federation ID.
CA, Certificate Authority - Any home server that issues and publicly attests to the validity of ID-Certs. In polyproto, only home servers are CAs.
Client - Any application used by an actor to connect to an instance.
CSR, Certificate Signing Request - A request sent to a CA to obtain a certificate. It holds information about the entity requesting the certificate, including their public identity key.
DN, Distinguished Name - A set of RDNs (Relative Distinguished Names) that uniquely identify a certificate. See https://ldap.com/ldap-dns-and-rdns/
Federation ID - A unique identifier; In public contexts, usually actor@subdomain.example.com, where bold parts are required and non-bold parts are optional.
Foreign server - An instance that an actor is not registered on; essentially a third party.
Home server - The instance that an actor is registered on. Any polyproto-core compliant server hosted on the same domain is also considered a home server. A home server is the instance that publicly attests to the validity of all legitimate ID-Certs issued under its FQDN. A domain can have many home servers, but only one per subdomain.
ID-CSR - A certificate signing request for a client's identity key pair. It is used to obtain an ID-Cert.
Identity - Synonymous with "Federation ID".
Identity Key Pair - A key pair associating an identity with a set of cryptographic keys used to sign and possibly encrypt messages.
Instance - A server hosting polyproto compliant software for clients.
Message, Messages: In the context of this protocol specification, a message is any piece of data sent by a client that is intended to be identifiable as being sent by a specific actor. To qualify as a "message", this piece of data must also, at any point in time, and also if only briefly, be visible to other users or to the unauthenticated public. Examples of things that would qualify as messages include:
- A message sent to another actor in a chat application
- A post on a social media platform
- A "like" interaction on a social media platform
- Reaction emojis in Discord-like chat applications
- Group join or leave messages
- Reporting a post or actor, if the report is not anonymous
P2 - Shortened form of polyproto.
P2 Extension - A polyproto extension.
polyproto-chat - The chat-API used by Polyphony. An extension of the polyproto protocol, defining the routes and capabilities of the chat-API used by Polyphony.
polyproto - The core federation protocol and APIs of polyproto, enabling identification and authorization on foreign servers. It is independent of the chat-API used.
Root Certificate - A certificate used to sign other certificates, establishing a chain of trust. In polyproto, only home servers have root certificates.
Service: Any application-specific implementation of polyproto, defined by a P2 extension. All services are P2 extensions, but not all P2 extensions are services. polyproto-chat is an example of a service.
Session - A specific period of authenticated interaction between a client and an instance. During the lifetime of a session, the client can perform actions as the actor they are authenticated as.
Session ID - See polyproto specification: Section 6.1.1.3