Request authorization

Request authorization in Alette Signal refers to the process of providing token holders or cookie handlers to the request blueprint bearer() middleware.

Sending tokens

To send a token to the server, pass a token holder to the bearer() middleware and execute the request:

const appQuery = query(
    bearer(jwtToken),
);

await appQuery.execute();

The bearer() middleware sends token headers to the server automatically, allowing the server to verify token validity:

const appQuery = query(
    bearer(jwtToken),
    // Done automatically under the hood
	// headers(() => jwtToken.toHeaders())
);

TIP

Token headers included by the bearer() middleware are not overridden by middleware cascading if there is no header key collision:

const appQuery = query(
    // Let's say the jwtToken returns
	// "{ Authorization: '...' }" headers
    bearer(jwtToken),
   	// Will be merged with token headers
   	headers({ 'X-Alette': 'Signal' }),
);

Sending cookies

To send a cookie to the server, pass a cookie handler to the bearer() middleware and execute the request:

const appQuery = query(
    bearer(authCookie),
);

await appQuery.execute();

The bearer() middleware instructs the request blueprint to include credentials automatically, allowing the server to verify cookie validity:

const appQuery = query(
    bearer(authCookie),
    // Done automatically under the hood
	// credentials('include')
);

TIP

To override default { credentials: "include" } set by the bearer() middleware for cookie handlers, use the credentials() middleware:

const appQuery = query(
    bearer(authCookie),
	credentials('same-origin')
);

Selective authorization

Selective authorization in Alette Signal refers to the process of sending tokens or cookies with a subset of requests, while ignoring others.

To configure selective authorization, pass the bearer() middleware with a token or a cookie to requests requiring authorization:

const queryWithAuth = query(
    bearer(jwtToken),
);

const anotherQueryWithAuth = queryWithAuth.with(
    /* ... */
)

const mutationWithoutAuth = mutation(
    /* ... */
)

TIP

To ensure a subset of requests share authorization behaviour automatically, turn request blueprints into factories:

// api/base.ts
const { query: baseQuery } = core.use(); 

export const query = baseQuery(
    bearer(jwtToken),
    /* ... */
).toFactory();

// api/posts.ts
import { query } from './base';

// Already contains "bearer(jwtToken)"
export const getPost = query(/* ... */);

Authorization errors

Authorization errors are errors thrown when the server determines that an authenticated user lacks permission to perform an action and returns a 401 or 403 HTTP Status code.

Some servers can also return a 419 HTTP Status code, indicating that the user's session or CSRF token has expired.

The bearer() middleware invalidates provided tokens and cookies automatically when the server returns 401 or 419 HTTP status code:

const myRequest = custom(
    bearer(authCookie),
	factory(() => {
        // Will invalidate authCookie
        throw new RequestFailedError({
			status: 401, // or 419
		})
	})
);

TIP

The query, mutation and custom request blueprints retry requests automatically when a 401 or 419 HTTP status code is returned from the server.

DANGER

The bearer() middleware does not retry requests automatically. To configure retries for request blueprints, refer to the Alette Signal request retrying guide.