Skip to main content

Auth API

So now that we understand the high-level of how Auth works and the specifics of the building blocks that make it possible, let's put all of that information together to understand the specific of how the Auth API works.

The Auth API is a set of REST endpoints that all server-side plugins of the Auth SDK implement. They enable wallet-based authentication and authorization for any API that they are added to. There are three key endpoints that the Auth API provides:

  • POST - /login
  • GET - /user
  • POST - /logout

Let's take a look at what each of these endpoints looks like in more detail, and the flow of how they all work together.

Login​

auth-api-1

The /login endpoint is the start of the whole Auth flow. It's a POST endpoint that expects to receive the sign-in with wallet payload from the client. The main purpose of this endpoint is to check that the user has made a valid sign-in with wallet request, and to issue them a signed JWT if they have for them to authenticate to other endpoints.

The /login endpoint goes through the following high-level steps to accomplish this:

  1. Check that the sign-in with wallet request is valid, secure, and hasn't expired, as specified in the sign-in with wallet section.
  2. Generate a signed JWT for the user to authenticate to other endpoints, as specified in the JWT section.
  3. Return the signed JWT to the client in both the response and the cookies, for compatibility across browser and non-browser clients.

User​

auth-api-2

The /user endpoint is a GET endpoint that allows the client to perioically check if the user is still logged in, and to get any associated user data that's relevant to the client (like profile data, for example).

It can accomplish this by going through the following high-level steps:

  1. Check that the user has sent a valid JWT in the request cookies or headers, as specified in the JWT section.
  2. If the user hasn't sent a valid JWT, return null
  3. Populate any session data stored on the JWT into the user object and any external user-associated data into the user object (like data from a database)
  4. Return the user object to the client

Logout​

auth-api-3

The /logout endpoint is the simplest of all of them. It's goal is simply to invalidate the users JWT and log them out of the application. It accomplishes this by deleting any client-side cookies with the JWT, and optionally invaliating the JWT if a database setup is used.

Protected Endpoints​

auth-api-4

Finally, we can take a look at how Auth can be used to protect additional endpoints, which is one of it's most important functions, as this comprises its authorization function.

Authorizing the user on an endpoint involves the following simple process:

  1. Obtain the identity of the authenticated user by a method similar to the /user endpoint (ie. by reading it off the JWT, if any is present)
  2. Grant permission to the user based on their identity

In every Auth plugin, this is handled by a simple helper function that you can add to your endpoints so you don't have to worry about the details of the process yourself.