Auth Object

Both auth() and getAuth() return an Auth object. This JavaScript object contains important information like the current user's session ID, user ID, and organization ID. It also contains methods to check for permissions and retrieve the current user's session token.

Auth object properties

sessionId string

The current user's session ID.

userId string

The current user's unique identifier.

orgId string | undefined

The current user's active organization ID.

orgRole OrganizationCustomRoleKey | undefined

The current user's active organization role.

orgSlug string |undefined

The current user's active organization slug.

orgPermissions OrganizationCustomPermissionKey[] | undefined

The current user's active organization permissions.

sessionClaims JwtPayload

The current user's session claims.

actor ActClaim | undefined

Holds identifier for the user that is impersonating the current user.

has() (isAuthorizedParams: CheckAuthorizationParamsWithCustomPermissions) => boolean

A function that returns a boolean based on the permission or role provided as parameter. Can be used for authorization.

getToken() ServerGetToken

A function that returns a promise that resolves to the current user's session token. Can also be used to retrieve a custom JWT template.

debug AuthObjectDebug

Used to help debug issues when using OneAuxilia in development.

OrganizationCustomRoleKey

The orgRole property on the Auth object has the type OrganizationCustomRoleKey.

OrganizationCustomRoleKey is a string that represents the user's role in the organization. OneAuxilia provides the default roles org:admin and org:member. However, you can create custom roles as well.

OrganizationCustomPermissionKey

The orgPermissions property on the Auth object has the type OrganizationCustomPermissionKey.

OrganizationCustomPermissionKey is a string that represents the permission of the user in the organization. OneAuxilia provides default System Permissions, and you can create custom permissions.

has()

has() can be used on both the frontend and the backend to determine if the user has a role or permission.

You can use has() anywhere OneAuxilia returns an Auth object:

auth() in Next.js App Router
useAuth() in Client Components, including during SSR
getAuth(request) in server contexts outside of the App Router and SSR (Remix Loaders, Node, Express, Fastify, etc)

has() has the following function signature:

function has(isAuthorizedParams: CheckAuthorizationParamsWithCustomPermissions) => boolean;

CheckAuthorizationParamsWithCustomPermissions

CheckAuthorizationParamsWithCustomPermissions has the following properties:

role string

The role to check for.

permission string

The permission to check for.

has() example

You can use has() to check if a user is authorized to access a component.

In the following example:

has() is used to check if the user has the org:team_settings:manage permission.
If the user does not have the permission, null is returned and the "Team Settings" component is not rendered.

app/page.tsx

import { auth } from '@oneAuxilia/nextjs/server';

export default async function Page() {
  const { has } = auth();

  const canManage = has({ permission:"org:team_settings:manage" });

  if(!canManage) return null;

  return <h1>Team Settings</h1>
}

getToken()

You can use getToken() on an Auth object to retrieve the user's session token. You can also use this method to retrieve a custom JWT template.

Tokens can only be generated if the user is signed in.

ServerGetToken

type ServerGetToken = (options?: ServerGetTokenOptions) => Promise<string | null>;

ServerGetTokenOptions

getToken() accepts an optional options parameter, which has the following properties:

template? string

The name of the custom JWT template to retrieve.

Use getToken() in the frontend

The Auth object is not available in the frontend. To use the getToken() method in the frontend:

For React-based applications, you can use the useAuth() hook. See the reference documentation for example usage.
For JavaScript applications, see the reference documentation for example usage.

Use getToken() in the backend

To use the getToken() method in the backend:

In App Router applications, use the auth() helper.

app/api/get-token-example/route.ts

import { auth } from "@oneauxilia/nextjs/server";

export async function GET() {
  const { getToken } = auth();

  const template = 'test';

  const token = await getToken({ template })

  return Response.json({ token })
}

In Pages Router applications, use the getAuth() helper.

pages/api/getToken.ts

import { getAuth } from '@oneauxilia/nextjs/server';
import type { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const { getToken } = getAuth(req);

  const template = 'test';

  const token = await getToken({ template });

  return res.json({token});
}

To use the getToken() method in the backend, you can acccess it using the Auth object returned by the request.

getToken.ts

app.post('/api/get-token',
  // OneAuxiliaExpressRequireAuth returns an error for unauthorized requests
  OneAuxiliaExpressRequireAuth(),

  // Optionally OneAuxiliaExpressWithAuth returns an empty user with no error
  // OneAuxiliaExpressWithAuth(),

  async (req, res) => {
    const getToken = req.auth.getToken

    const template = 'test'

    const token = await getToken({ template })

    res.json({ token })
  })

To use the getToken() method in the backend, you can access it using the getAuth() function.

app/routes/get-token.ts

import { getAuth } from "@oneauxilia/remix/ssr.server"
import { ActionFunction, json } from "@remix-run/node"

export const action: ActionFunction = async (req) => {
  const { getToken } = await getAuth(req)

  const template = 'test';

  const token = await getToken({ template });

  return json({ token })
}

Auth object example without active organization

The following is an example of the Auth object without an active organization:

{
  sessionId: 'sess_2GaMqUCB3Sc1WNAkWuNzsnYVVEy',
  userId: 'user_2F2u1wtUyUlxKgFkKqtJNtpJJWj',
  orgId: null,
  orgRole: null,
  orgSlug: null,
  orgPermissions: null,
  has: [Function (anonymous)],
  getToken: [AsyncFunction (anonymous)],
  claims: {
    azp: 'http://localhost:3000',
    exp: 1666622607,
    iat: 1666622547,
    iss: 'https://oneauxilia.quiet.muskox-85.lcl.dev',
    nbf: 1666622537,
    sid: 'sess_2GaMqUCB3Sc1WNAkWuNzsnYVVEy',
    sub: 'user_2F2u1wtUyUlxKgFkKqtJNtpJJWj'
  }
}

Auth object example with active organization

The following is an example of the Auth object with an active organization:

{
  sessionId: 'sess_2GaMqUCB3Sc1WNAkWuNzsnYVVEy',
  userId: 'user_2F2u1wtUyUlxKgFkKqtJNtpJJWj',
  orgId: 'org_2ZVFfVAkt4ocVjHL0KTdL94AhXK',
  orgRole: 'org:admin',
  orgSlug: undefined,
  orgPermissions: ['org:team_settings:manage'], // Custom permissions
  has: [Function (anonymous)],
  getToken: [AsyncFunction (anonymous)],
  claims: {
    azp: 'http://localhost:3000',
    exp: 1666622607,
    iat: 1666622547,
    iss: 'https://oneauxilia.quiet.muskox-85.lcl.dev',
    nbf: 1666622537,
    sid: 'sess_2GaMqUCB3Sc1WNAkWuNzsnYVVEy',
    sub: 'user_2F2u1wtUyUlxKgFkKqtJNtpJJWj'
  }
}

Last updated 4 months ago