Skip to content

Local (email/password)

Authenticating to the API using local credentials (email/password) is implemented by a stored procedure that lives in your database. This means that you can addapt the login function to your specific needs.

The function definition can be found in your local project in db/src/api/login.sql or you can view it directly in the starter kit repository

The table used to store application users is data.user defined in db/src/data/user.sql

By default, the login function, upon successful login, will create a cookie by the name SESSIONID, the content of which is a jwt token with the following keys as payload:

  • role — the database role to assume when executing queries for this particular user
  • user_id — the value of the id column from the data.user table. This property can/is used when defining authorization rules
  • exp — a unix timestamp that defines when the token expires

Calling the login function

curl -X POST --cookie-jar cookies.txt \
-d '{"email":"alice@email.com","password":"pass"}' \
http://localhost:8080/auth/login
const endpoint = 'http://localhost:8080';
await fetch(endpoint+'/auth/login', {
    method: 'POST',
    body: JSON.stringify({email:'alice@email.com',password:'pass'})
});
import axios from 'axios';
const client = axios.create({
    baseURL: 'http://localhost:8080'
    withCredentials: true
});
await client.post('/auth/login', {email:'alice@email.com',password:'pass'});
import { ApolloClient, InMemoryCache, createHttpLink, gql } from '@apollo/client';
const link = createHttpLink({
    uri: 'http://localhost:8080/graphql/simple',
    credentials: 'same-origin'
});
const client = new ApolloClient({
    cache: new InMemoryCache(),
    link
});
await client.query({ 
    query: gql` 
        mutation {
            login(email: "alice@email.com", password: "pass"){
                id 
            } 
        }
    `
});

To perform api requests as an authenticated user, the client will need to send the SESSIONID cookie along with the request. Each HTTP client has his own particular way of managing cookies.

Here is an example of an authenticated call (provided the login call was performed with the http client initialized as in the example above)

curl --cookie cookies.txt http://localhost:8080/rest/todos?select=id,todo
const response = await fetch(endpoint+'/rest/todos?select=id,todo', {
    credentials: 'same-origin'
});
const response = await client.get('/rest/todos?select=id,todo');
const response = await client.query({ 
    query: gql`
        query { 
            todos {
                id todo 
            } 
        }
    `
});

Note

In most of the reference documentation, the api calls in the examples are performed as unauthenticated calls. You will need to initialize your HTTP clients as in the example above in order for them to send the authentication cookie (jwt token) with each request.