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.