Lightquark API v4 (active dev)

Lightquark authentication works with email and password

SSA (Scoped Secure Authentication) is a way for applications that are not full Lightquark clients to authenticate against a network without getting full permissions or login credentials.

The rough flow is something like this:

• The user hits log in on an external tool and chooses their network

• The external tool redirects them to a web+lq:// authorization link (possibly https based /d/ link?)

• The Lightquark client that is registered to handle the link presents an authorization screen explaining that external tool is requesting some permissions.

• User approves the authorization request, and the client generates an SSA token (/v4/auth/ssa/authorize) with the specified scopes

• Client redirects user back to external tool at the url specified in the originalk authorization link with access_token and refresh_token query parameters set

• The user is now signed in on external tool

The authorization link format is as follows:

web+lq://networkBase:s:authorize?scopes=123&redirect_uri=abc

• networkBase could be lightquark.network/testnet for example, so the client looks for the ssa endpoint at https://lightquark.network/testnet/v4/auth/ssa/authorize, though ideally the client uses gatekeeper and requests this from it's assigned app server, assuming the authorization is on the same network as the one in use at the moment

• s is the link type, in this case SSA

• authorize is technically the relevantId here, which really is just the SSA action to perform

• scopes=123 requesting scopes 123, scopes explained below

• redirect_uri=abc the redirect uri should be an url encoded uri to take the user to after authorization is complete, and the tokens are provided as query parameters

Scopes

Scopes are a funky little 64 bit integer :) Each bit that is 1 indicates a permission is present, while a 0 indicates that it is not.

[Flags]
public enum TokenScope : long
{
    UserRead = 1 << 0, // Can read data about user profiles (including status and preferences)
    UserWriteStatus = 1 << 1, // Can update or clear the status
    UserWriteAvatar = 1 << 2, // Can update or reset the avatar
    UserWritePreference = 1 << 3, // Can update or clear preferences
    Gateway = 1 << 4, // Can connect to the gateway, this can expose data in update events,
    // that is otherwise not requested with other scopes. RPC is limited by scopes however.
    QuarkRead = 1 << 5, // Read data about quarks you're in, including the list of channels (including DMs)
    QuarkCreate = 1 << 6, // Create quarks
    QuarkWrite = 1 << 7, // Update quarks
    QuarkDelete = 1 << 8, // Delete quarks
    QuarkManageEmoji = 1 << 9, // Create, update and delete emotes
    ChannelCreate = 1 << 10, // Create channels (including DMs)
    ChannelDelete = 1 << 11, // Delete channels
    ChannelWrite = 1 << 12, // Update channels (unused as of 15.12.2024)
    MessageRead = 1 << 13, // Read messages in channels (and DMs)
    MessageWrite = 1 << 14, // Send messages
    QuarkInvite = 1 << 15, // See and create quark invites
    QuarkJoin = 1 << 16, // Join quarks
    QuarkLeave = 1 << 17, // Leave quarks
    Password = 1 << 18 // This scope can't be requested, it just means if the token was created with a password rather than SSA
}

Authorization screen

The authorization screen should achieve these goals:

• Obtain consent from the user to permit [external-tool] to use their account

• Explain what permissions are being granted

• Make it clear that the application requesting access cannot be verified, and may not be trustworthy