Core Routes: No registration needed

All API endpoints needed for Client-Home Server communication. This Page only includes routes, for which a client does not need a "Client-Home Server relationship" with the server.

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¶

Routes concerning federated identities, such as authentication and ID-Cert management.

GET Challenge string¶

/.p2/core/v1/challenge

Request a challenge string. See the type definition or the corresponding protocol definition chapter for more information.

Request¶

Body¶

This request has no body.

Response¶

200 OK

Body¶

Name	Type	Description
`challenge`	String	The challenge string, which the client should sign with its private identity key.
`expires`	integer	The UNIX timestamp after which the challenge expires. u64 integer

JSON

{
    "challenge": "UH675678rbnFGNHJV2ijcnr3ghjHV74jah...",
    "expires": "1620000000"
}

PUT Rotate Server Identity Key ¶

/.p2/core/v1/key/server

Rotate the server's identity key.

Request¶

Body¶

This request has no body.

Response¶

200 OK

Body¶

Type	Description
String, PEM	The servers' new ID-Cert, encoded as PEM

JSON

GET Server Public ID-Cert¶

/.p2/core/v1/idcert/server

Request the server's public identity certificate.

Request¶

Body¶

Name	Type	Description
`timestamp`	String	UNIX-Timestamp. If specified, the server will return the ID-Cert that it had at the specified time

JSON

{
    "timestamp": "1620000000"
}

Response¶

200 OK

Body¶

Type	Description
String, PEM	The servers' public ID-Cert, PEM encoded.

JSON

GET Server Public Key¶

/.p2/core/v1/key/server

Request the server's public key.

Request¶

Body¶

Name	Type	Description
`timestamp`	String	UNIX-Timestamp. If specified, the server will return the public key that it had at the specified time

JSON

{
    "timestamp": "1620000000"
}

Response¶

200 OK

Body¶

Type	Description
String, PEM	PEM encoded X.509 `SubjectPublicKeyInfo` information about the server's public identity key.

JSON

GET Actor ID-Cert(s)¶

/.p2/core/v1/idcert/actor/:fid

Request the ID-Certs of a specific actor. The specified actor must be registered on this server.

Request¶

Parameters¶

Name	Type	Description
`fid`	String, Federation ID	The ID of the actor whose ID-Cert(s) should be returned.

Body¶

Name	Type	Description
`timestamp`	Unsigned 64-Bit Integer	UNIX-Timestamp. If specified, the server will return the ID-Cert(s) which the actor had at the specified time
`session_id`	String	Request the ID-Cert for a specific session ID.

JSON

{
    "timestamp": "1620000000",
    "session_id": "593b30d8-0c98-4393-9331-988281b46782"
}

Response¶

200 OK

Body¶

JSON-Array of Object(s), each object containing "id_cert" (PEM encoded ID-Cert) and "invalidated" (boolean).

JSON

[
    {
        "id_cert": " -----BEGIN CERTIFICATE-----MIIH/TC...",
        "invalidated": false
    }
]

Note

The invalidated array contains a boolean for each ID-Cert in the idcerts array. The position of the boolean in the invalidated array corresponds to the position of the ID-Cert in the idcerts array.

PUT Update session ID-Cert ¶

/.p2/core/v1/session/idcert/extern

Lets a foreign server know that the ID-Cert of this session has changed.

Request¶

Body¶

Type	Description
String, PEM, Base64	The new ID-Cert for this session ID.

Text Only

[...]

Response¶

201 Created

Body¶

This response has no body.

DELETE Delete Session¶

/.p2/core/v1/session

Invalidate a session token by naming the session ID associated with it.

Request¶

Body¶

Name	Type	Description
`session_id`	String	The session ID to invalidate.

JSON

{
    "session_id": "593b30d8-0c98-4393-9331-988281b46782"
}

Response¶

204 No Content

This response has no body.

Services¶

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

GET Discover services of actor¶

.p2/core/v1/services/discover/:fid

Fetch a list of all services that the actor has made discoverable. Clients should not expect this list to be ordered in any particular way.

Request¶

Parameters¶

Name	Type	Description
`fid`	String, Federation ID	The ID of the actor whose services should be returned.

Body¶

Name	Type	Description
limit	Unsigned Integer	The maximum number of services to return.

The body is optional. Not specifying a limit will return all services.

JSON

{
    "limit": 5
}

Response¶

200 OK204 No Content404 Not Found

Body¶

JSON array of service objects. A list of all services which the actor has made discoverable.

JSON

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

Returned, if the actor has not made any services discoverable.

Body¶

This response has no body.

Returned, if the specified actor does not exist.

Body¶

This response has no body.

GET Discover single service of actor¶

.p2/core/v1/services/discover/:fid/:service

Get all service providers an actor is registered with, limited to a specific service. Clients should not expect this list to be ordered in any particular way.

Request¶

Parameters¶

Name	Type	Description
`fid`	String, Federation ID	The ID of the actor whose discoverable entries should be returned.

Body¶

Name	Type	Description	Required?
`limit`	Unsigned Integer	The maximum number of services to return.	No
`name`	String	The service name to filter the query by.	Yes

Not specifying a limit will return all services. Specifying a limit value of 1 will return only the primary service provider.

JSON

{
    "limit": 5,
    "name": "example-service"
}

Response¶

200 OK204 No Content404 Not Found

Body¶

JSON array of service objects, filtered by the specified service. Will be an array, regardless of the only_primary parameter.

JSON

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

Returned, if there are no discoverable entries for the specified service.

Body¶

This response has no body.

Returned, if the specified actor does not exist.

Body¶

This response has no body.

Other¶

Routes not fitting into another category.

GET Events ¶

/.p2/core/v1/events

Fetch Gateway events via REST.

Request¶

Body¶

This request has no body.

Response¶

200 OK409 No Content

Body¶

Type	Description
JSON-Array of Events	All WebSocket Events this session has missed since disconnecting from the WebSocket, or since last querying this endpoint.

Returned if there are no events to inform the client about.

Body¶

This response has no body.

Migration¶

Routes concerned with identity migration and re-signing messages.

POST Set up a redirect for migrating identities ¶

.p2/core/v1/migration/redirect/extern

GET Request message re-signing ¶

.p2/core/v1/migration/messages/extern

POST Commit re-signed messages ¶

.p2/core/v1/migration/messages/extern

TODO: "All challenge strings and their responses created in the context of account migration must be made public to ensure that a chain of trust can be maintained"

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