Reference: protocol.auth.v1

Services

AuthService

The service containing authorization/entication methods Fields

Federate

protocol.auth.v1.FederateRequest -> protocol.auth.v1.FederateResponse

Federate with a foreignserver, obtaining a token you can use to call LoginFederated on it


FederateRequest

The request to federate with a foreign server.

Fields

server_id

Type: optional string

The server ID foreign server you want to federate with


FederateResponse

The reply to a successful federation request, containing the token you need to present to the foreign server.

Fields

token

Type: optional protocol.harmonytypes.v1.Token

A harmonytypes.v1.Token whose data field is a serialized TokenData message. It is signed with the homeserver’s private key.


LoginFederated

protocol.auth.v1.LoginFederatedRequest -> protocol.auth.v1.LoginFederatedResponse

Present a token to a foreignserver from a Federate call on your homeserver in order to login


LoginFederatedRequest

Log into a foreignserver using a token from your homeserver, obtained through a FederateRequest

Fields

auth_token

Type: optional protocol.harmonytypes.v1.Token

A harmonytypes.v1.Token whose data field is a serialized TokenData message. It is signed with the homeserver’s private key.

server_id

Type: optional string

The server ID of the homeserver that the auth token is from


LoginFederatedResponse

Used in LoginFederated endpoint.

Fields

session

Type: optional protocol.auth.v1.Session

The user’s session.


Key

protocol.auth.v1.KeyRequest -> protocol.auth.v1.KeyResponse

Returns the public key of this server


KeyRequest

Used in Key endpoint.

This item has no fields.


KeyResponse

Contains a key’s bytes.

Fields

key

Type: optional bytes

key: the bytes of the public key.


BeginAuth

protocol.auth.v1.BeginAuthRequest -> protocol.auth.v1.BeginAuthResponse

Begins an authentication session


BeginAuthRequest

Used in BeginAuth endpoint.

Fields

for_guest_token

Type: optional string

If provided, this is the guest token for the account being upgraded from a guest account to a full account during the auth flow.

This token is provided by the server at the end of the auth flow that created the guest account.


BeginAuthResponse

BeginAuthResponse The return type of BeginAuth, containing the auth_id that will be used for the authentication section

Fields

auth_id

Type: optional string

auth_id: the ID of this auth session


NextStep

protocol.auth.v1.NextStepRequest -> protocol.auth.v1.NextStepResponse

Goes to the next step of the authentication session, possibly presenting user input

NextStepResponse

Used in NextStep endpoint.

Fields

step

Type: optional protocol.auth.v1.AuthStep

step: the next step in the authentication process


StepBack

protocol.auth.v1.StepBackRequest -> protocol.auth.v1.StepBackResponse

Goes to the previous step of the authentication session if possible


StepBackRequest

StepBackRequest A request to go back 1 step

Fields

auth_id

Type: optional string

auth_id: the authentication session the user wants to go back in


StepBackResponse

Used in StepBack endpoint.

Fields

step

Type: optional protocol.auth.v1.AuthStep

step: the previous step in the authentication process


StreamSteps

protocol.auth.v1.StreamStepsRequest -> streaming protocol.auth.v1.StreamStepsResponse

Consume the steps of an authentication session as a stream


StreamStepsRequest

StreamStepsRequest Required to be initiated by all authenticating clients Allows the server to send steps

Fields

auth_id

Type: optional string

auth_id: the authorization session who’s steps you want to stream


StreamStepsResponse

Used in StreamSteps endpoint.

Fields

step

Type: optional protocol.auth.v1.AuthStep

step: the next step in the authentication process


CheckLoggedIn

protocol.auth.v1.CheckLoggedInRequest -> protocol.auth.v1.CheckLoggedInResponse

Check whether or not you’re logged in and the session is valid


CheckLoggedInRequest

Used in CheckLoggedIn endpoint.

This item has no fields.


CheckLoggedInResponse

Used in CheckLoggedIn endpoint.

This item has no fields.

Standalone Message Types

Session

Session Session contains the information for a new session; the user_id you logged in as and the session_token which should be passed to authorisation

Fields

user_id

Type: optional uint64

user_id: the ID of the user you logged in as

session_token

Type: optional string

session_token: the session token to use in authorization

guest_token

Type: optional string

A token allowing for this account to be upgraded to a “full” account by beginning an auth session and providing this token.

The guest token only exists to upgrade a guest account to a full account, and does not permit logging in with a guest account on more than one session.

A “guest token” MAY be provided to BeginAuth to begin an authorization process that will upgrade the guest account to a full account if completed successfully. This MUST only affect now being able to log into the account with more than one session, and MUST not change other information about the account, such as username and password.


AuthStep

AuthStep A step in the authentication process Contains a variety of different types of views It is recommended to have a fallback_url specified For non-trivial authentication procedures (such as captchas)

Fields

fallback_url

Type: optional string

fallback_url: unused

can_go_back

Type: optional bool

can_go_back: whether or not the client can request the server to send the previous step

choice

Type: optional protocol.auth.v1.AuthStep.Choice

choice: the user must pick a thing out of a list of options

form

Type: optional protocol.auth.v1.AuthStep.Form

form: the user must complete a form

session

Type: optional protocol.auth.v1.Session

session: you’ve completed auth, and have a session

waiting

Type: optional protocol.auth.v1.AuthStep.Waiting

waiting: you’re waiting on something


AuthStep.Choice

Fields

title

Type: optional string

options

Type: repeated string


AuthStep.Form

Fields

title

Type: optional string

fields

Type: repeated protocol.auth.v1.AuthStep.Form.FormField


AuthStep.Form.FormField

Fields

name

Type: optional string

type

Type: optional string


AuthStep.Waiting

Fields

title

Type: optional string

description

Type: optional string


NextStepRequest

NextStepRequest contains the client’s response to the server’s challenge This needs to be called first with no arguments to receive the first step

Fields

auth_id

Type: optional string

auth_id: the authentication session you want the next step of

choice

Type: optional protocol.auth.v1.NextStepRequest.Choice

choice: the choice the user picked

form

Type: optional protocol.auth.v1.NextStepRequest.Form

form: the form the user filled out


NextStepRequest.Choice

Fields

choice

Type: optional string


NextStepRequest.FormFields

Fields

bytes

Type: optional bytes

string

Type: optional string

number

Type: optional int64


NextStepRequest.Form

Fields

fields

Type: repeated protocol.auth.v1.NextStepRequest.FormFields


TokenData

Information sent by a client’s homeserver, in a harmonytypes.v1.Token. It will be sent to a foreignserver by the client.

Fields

user_id

Type: optional uint64

The client’s user ID on the homeserver.

server_id

Type: optional string

The foreignserver’s server ID.

username

Type: optional string

The username of the client.

avatar

Type: optional string

The avatar of the client.