Authentication

Create session

First step is creating a message, CreateSessionRequest, with username, password and a device UUID.

The device_uuid is an identifier from which resource the request has been made. The device_uuid needs to be unique per user and resource.

If the client authenticates with the same device_uuid from another resource all other sessions will be terminated.

message CreateSessionRequest {
    string username = 1;
    string password = 2;
    string device_uuid = 3;
}

The message is sent to the SessionService to get back an authentication token that the client will use in subsequent requests and an reissue token that will be used to re-authentication as explained below.

sequenceDiagram
    participant Client
    participant SessionsService
    Client->>SessionsService: CreateSessionRequest
    SessionsService-->>Client: CreateSessionResponse

Store the tokens in some form of local cache so it is available to the client and don't re-authenticate on each request.

message CreateSessionResponse {
    string auth_token = 1;
    string reissue_token = 2;
    uint32 exp = 3;
    uint64 user_id = 4;
    string username = 5;
    string user_uuid = 6;
}

Re-issue session

An authentication token (auth_token) is valid for 2 weeks and to extend the validity the client can send an request to reissue the token which extends it an additional two weeks.

message ReissueSessionRequest {
    string reissue_token = 1;
}

To re-issue an authentication token you need to send an ReissueSessionRequest with the reissue token returned when the session was created.

sequenceDiagram
    participant Client
    participant SessionsService
    Client->>SessionsService: ReissueSessionRequest
    SessionsService-->>Client: ReissueSessionResponse

You will get back an ReissueSessionResponse with the extend auth_token and a new re-issue token if you need to extend the validity further.

message ReissueSessionResponse {
    string auth_token = 1;
    string reissue_token = 2;
    uint32 exp = 3;
    uint64 user_id = 4;
    string username = 5;
    string user_uuid = 6;
}

Destroy session

To invalidate an authentication session send an empty DestroySessionRequest message to the SessionsService.

sequenceDiagram
    participant Client
    participant SessionsService
    Client->>SessionsService: DestroySessionRequest
    SessionsService-->>Client: DestroySessionResponse

message DestroySessionRequest {

}

You will get back an empty DestroySessionResponse to confirm that the auth token has been invalidated.

message DestroySessionResponse {

}