Authentication Routes: No registration needed

All API endpoints needed for implementing polyproto-auth. 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.

POST Create Identity¶

/.p2/core/v1/register

Creates an identity on a given server.

Request¶

Body¶

TODO: Re-evaluate if auth_payload is needed here.

Name	Type	Description
`actor_name`	String	The preferred name for this new identity.
`auth_payload`	JSON-Object	n. A.

JSON

{
    "actor_name": "alice",
    "auth_payload": {
        "password": "3c4589y70masfnmAML2"
    }
}

Response¶

201 Created409 Conflict

Text Only

##### Body

| Name                                                                                                                                                                                                                       | Type        | Description                                                               |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
| `fid`                                                                                                                                                                                                                      | String      | The [Federation ID](../../Glossary.md#federation-id) of the new identity. |
| `payload` :material-help:{title="This field is optional."} :material-code-braces:{title="The actual contents of this attribute are implementation-specific. polyproto-core does not provide any defaults for this field."} | JSON-Object | -                                                                         |

```json
{
    "fid": "[email protected]",
    "payload": {
        "some_account_information": "important information",
        "is_awesome": true
    }
}
```

Text Only

Returned when the requested actor name is already taken within the namespace.

##### Body

```json
{
    "errcode": 409,
    "error": "P2CORE_FEDERATION_ID_TAKEN"
}
```

POST Identify¶

/.p2/core/v1/session/identify

Identify on a foreign server and receive a session token.

Request¶

Body¶

Name	Type	Description
`challenge`	String	The completed challenge, consisting of a UTF-8 encoded signature value and the original challenge string. The signature value must have been created using the private identity key of that actor.
`id_cert`	String, PEM, Base64	The client's ID-Cert, encoded in PEM & Base64.
`auth_payload`	JSON-Object	-

JSON

{
    "completed_challenge": {
        "challenge": "UH675678rbnFGNHJV2ijcnr3ghjHV74jah...",
        "signature": "Ac4hjv2ijcnr3ghjHV74jahUH675678rbnFGNHJV..."
    },
    "id_cert": "gA3hjv2ijcnr3ghjHV74jahUH675678rbnFGNHJV...",
    "auth_payload": {
        "my_custom_attribute": "my_custom_value"
    }
}

Response¶

201 Created

Body¶

Name	Type	Description
`token`	String	A session token, to be used for further identification/authentication
`payload`	JSON-Object	-

JSON

{
    "token": "G5a6hjv2ijcnr3ghjHV74jahUH675678rbnFGNHJV...",
    "payload": {
        "my_custom_response_attribute": "my_custom_response_value"
    }
}

PUT Revoke session authentication ¶

/.p2/core/v1/session/revoke

Revoke the current session's authentication by having the server invalidate the session token. Can also be seen as a "logout" operation.

Request¶

Body¶

This request has no body.

Response¶

204 No Content

Body¶

This response has no body.

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