# Web API
The primary usecase for a library like oidc-spa is to use it to authenticate a REST, tRPC, or Websocket API.
Let's see a very basic REST API example:
{% tabs %}
{% tab title="Vanilla API" %}
Initialize oidc-spa and expose the oidc instance as a promise:
{% code title="src/oidc.ts" %}
```typescript
import { createOidc } from "oidc-spa";
export const prOidc = createOidc({/* ... */});
```
{% endcode %}
Create a REST API Client that adds the OIDC Access Token as Autorization header to every HTTP request:
import axios from "axios";
import { prOidc } from "oidc";
type Api = {
getTodos: () => Promise<{ id: number; title: string; }[]>;
addTodo: (todo: { title: string; }) => Promise<void>;
};
const axiosInstance = axios.create({ baseURL: import.meta.env.API_URL });
axiosInstance.interceptors.request.use(async config => {
const oidc= await prOidc;
if( !oidc.isUserLoggedIn ){
throw new Error("We made a logic error: The user should be logged in at this point");
}
config.headers.Authorization = `Bearer ${oidc.getTokens().accessToken}`;
return config;
});
export const api: Api = {
getTodo: ()=> axiosInstance.get("/todo").then(response => response.data),
addTodo: todo => axiosInstance.post("/todo", todo).then(response => response.data)
};
{% endtab %}
{% tab title="React API" %}
Initialize the React adapter of oidc-spa and expose the prOidc object, a promise of the vanilla OIDC API:
import { createReactOidc } from "oidc-spa/react";
export const {
OidcProvider,
useOidc,
getOidc
} = createReactOidc(/* ... */);
Create a REST API Client that adds the OIDC Access Token as Autorization header to every HTTP request:
import axios from "axios";
import { getOidc } from "oidc";
type Api = {
getTodos: () => Promise<{ id: number; title: string; }[]>;
addTodo: (todo: { title: string; }) => Promise<void>;
};
const axiosInstance = axios.create({ baseURL: import.meta.env.API_URL });
axiosInstance.interceptors.request.use(async config => {
const oidc= await getOidc();
if( !oidc.isUserLoggedIn ){
throw new Error("We made a logic error: The user should be logged in at this point");
}
config.headers.Authorization = `Bearer ${oidc.getTokens().accessToken}`;
return config;
});
export const api: Api = {
getTodo: ()=> axiosInstance.get("/todo").then(response => response.data),
addTodo: todo => axiosInstance.post("/todo", todo).then(response => response.data)
};
Using your REST API client in your REACT components:
import { api } from "../api";
type Todo= {
id: number;
title: string;
};
function UserTodos(){
const [todos, setTodos] = useState<Todo[] | undefined>(undefined);
useEffect(
()=> {
api.getTodos().then(todos => setTodos(todos));
},
[]
);
if(todos === undefined){
return <>Loading your todos items ⌛️</>
}
return (
<ul>
{todos.map(todo => (
<li key={todo.id}>{todo.title}</li>
))}
</ul>
);
}
{% hint style="info" %}
This example is purposefully very basic to minimize noise but in your App you should consider using [tRPC](https://trpc.io/) (if you have JS backend) and [TanStack Query](https://tanstack.com/query/v3).
{% endhint %}
{% endtab %}
{% endtabs %}
## Backend
If you're implementing a JavaScript Backend (Node/Deno/webworker) oidc-spa also exposes an utility to help you validate and decode the access token that your client sends in the authorization header. \
Granted, this is fully optional feel free to use anything else. \
\
Let's assume we have a Node.js REST API build with Express or Hono. \
You can create an oidc file as such:
{% code title="src/oidc.ts" %}
```typescript
import { createOidcBackend } from "oidc-spa/backend";
import { z } from "zod";
import { HTTPException } from "hono/http-exception";
export async function createDecodeAccessToken() {
const oidcIssuerUri = process.env.OIDC_ISSUER
if (oidcIssuerUri === undefined) {
throw new Error("OIDC_ISSUER must be defined in the environment variables")
}
const { verifyAndDecodeAccessToken } = await createOidcBackend({
issuerUri: oidcIssuerUri,
decodedAccessTokenSchema: z.object({
sub: z.string(),
realm_access: z.object({
roles: z.array(z.string())
})
// Some other info you might want to read from the accessToken, example:
// preferred_username: z.string()
})
});
function decodeAccessToken(params: {
authorizationHeaderValue: string | undefined;
requiredRole?: string;
}) {
const { authorizationHeaderValue, requiredRole } = params;
if( authorizationHeaderValue === undefined ){
throw new HTTPException(401);
}
const result = verifyAndDecodeAccessToken({
accessToken: authorizationHeaderValue.replace(/^Bearer /, "")
});
if( !result.isValid ){
switch( result.errorCase ){
case "does not respect schema":
throw new Error(`The access token does not respect the schema ${result.errorMessage}`);
case "invalid signature":
case "expired":
throw new HTTPException(401);
}
}
const { decodedAccessToken } = result;
if(
requiredRole !== undefined &&
!decodedAccessToken.ream_access.roles.includes(requiredRole)
){
throw new HTTPException(401);
}
return decodedAccessToken;
}
return { decodeAccessToken };
}
```
{% endcode %}
Then you can enforce that some endpoints of your API requires the user to be authenticated, in this example we use Hono:
import { z, createRoute, OpenAPIHono } from "@hono/zod-openapi";
import { serve } from "@hono/node-server"
import { HTTPException } from "hono/http-exception";
import { getUserTodoStore } from "./todo";
import { createDecodeAccessToken } from "./oidc";
(async function main() {
const { decodeAccessToken } = await createDecodeAccessToken();
const app = new OpenAPIHono();
{
const route = createRoute({
method: 'get',
path: '/todos',
responses: {/* ... */}
});
app.openapi(route, async c => {
const decodedAccessToken = decodeAccessToken({
authorizationHeaderValue: c.req.header("Authorization")
});
if (decodedAccessToken === undefined) {
throw new HTTPException(401);
}
const todos = getUserTodoStore(decodedAccessToken.sub).getAll();
return c.json(todos);
});
}
const port = parseInt(process.env.PORT);
serve({
fetch: app.fetch,
port
})
console.log(`\nServer running. OpenAPI documentation available at http://localhost:${port}/doc`)
})();
## Comprehensive example
If you're looking for a comprehensive Backend+Frontend example you can refer to Insee's project
{% embed url="" %}
The app is live here:
{% embed url="" %}
The frontend (Vite project):
{% embed url="" %}
The backend (Node TODO App REST API):
{% embed url="" %}