Auth

The Auth module is used to securely authenticate users on the server side. It provides a number of methods for signing in, signing out, and managing user sessions.

For full-stack applications, much of this would be handled with components and APIs, but in some cases you may need to use the server-side SDK to manage user sessions.

​

login

The nile.api.login method is used to login as a user.

​

Parameters

• email: The email of the user to login as.
• password: The password of the user to login as.
• config: Additional configuration options. Currently there is only one option:
  • returnResponse: If true, the method will return the result of the login attempt as a response object. If false, the method will set the corresponding session cookie if the login attempt succeeds and leave it unset if the login attempt fails.

​

Examples

Both examples below will print out the session token for the authenticated user. Do not actually print out the user’s session token in production - it should be kept secret.

Worth noting that the header name is different in each case. set-cookie is used for the response object and cookie is used for Nile’s headers object.

await nile.api.login({
  email: 'delete@me.com',
  password: 'deleteme',
});

const authCookie = nile.api.headers?.get('cookie');
if (!authCookie) {
    throw new Error('Login failed. No auth cookie found');
}

const [, token] =
    /((__Secure-)?nile\.session-token=.+?);/.exec(authCookie) ?? [];
if (!token) {
    throw new Error('Login failed. No session token found in auth cookie');
}
console.log('Session token: ', token)

​

signOut

The nile.api.auth.signOut method is used to sign out a user. Calling this method will remove the headers that were set during the login process.

It follows a two-step process similar to how sign-out works in the browser, ensuring CSRF protection and API consistency.

• The CSRF token is extracted and passed along with the request.
• The request is made with the appropriate headers, including the user’s cookies.
• The callback-url cookie is introspected and used as the origin, ensuring Nile Auth correctly handles the redirect after logout.

​

Returns

A promise that resolves to:

• A url object with the local signout url if the sign out was successful.
• A response object with 400 status code if the csrf token is missing.

​

Examples

const signoutRes = await nile.api.auth.signOut();
console.log(signoutRes);
// Example response:
// { url: 'http://localhost:3000/api/auth/signout?csrf=true' }
console.log(nile.api.headers);
// After signout, we expect the headers to be empty
// Headers {}

​

getSession

The nile.api.auth.getSession method is used to get the current session. Alternatively nile.api.session can be used the same way.

​

Returns

A promise that resolves to either a JWT or an ActiveSession object. Depending on the type of the current session.

type JWT = {
  email: string;
  sub: string;
  id: string;
  iat: number;
  exp: number;
  jti: string;
};

If there’s no active session, the method will return undefined.

​

Examples

const session = await nile.api.auth.getSession();
console.log(session);
// Example response (ActiveSession):
//{
//  user: {
//    id: '01961743-d5e7-73bb-8e65-8d403e69e275',
//    email: 'userB@me.com',
//    emailVerified: null
//  },
//  expires: '2025-05-09T00:28:40.000Z'
//}

​

getCsrf

The nile.api.auth.getCsrf method is used to get a new CSRF token. Typically, you will not need to use this method as the CSRF token is automatically retrieved during the login process and stored as a cookie.

​

Returns

A promise that resolves to a string of the CSRF token.

​

Examples

const csrf = await nile.api.auth.getCsrf();
console.log(csrf);

​

listProviders

The nile.api.auth.listProviders method is used to get the list of authentication providers enabled for the current tenant.

​

Returns

A promise that resolves to a mapped type “Providers”, with the key being the provider name and the value being the provider object.

type ProviderName =
  | 'discord'
  | 'github'
  | 'google'
  | 'hubspot'
  | 'linkedin'
  | 'slack'
  | 'twitter'
  | 'email'
  | 'credentials' // this is email/password
  | 'azure';

type Providers = {
  [providerName in ProviderName]: Provider;
};

type Provider = {
  id: string;
  name: string;
  type: string;
  signinUrl: string;
  callbackUr: string;
};

​

Examples

const providers = await nile.api.auth.listProviders();
console.log(providers);
// Example response:
// {
//   credentials: {
//     id: 'credentials',
//     name: 'credentials',
//     type: 'credentials',
//     signinUrl: 'http://localhost:3000/api/auth/signin/credentials',
//     callbackUrl: 'http://localhost:3000/api/auth/callback/credentials'
//   },
//   github: {
//     id: 'github',
//     name: 'GitHub',
//     type: 'oauth',
//     signinUrl: 'http://localhost:3000/api/auth/signin/github',
//     callbackUrl: 'http://localhost:3000/api/auth/callback/github'
//   }
// }

​

headers

The nile.api.headers object is used to get or manually set the headers of the current session. If you are manually modifying the cookie, you need to make sure you leave all the Nile entries intact, otherwise the session will break.

​

Examples

console.log(nile.api.headers);
nile.api.headers = new Headers({
    'X-Tenant-Id': tenantA.id,
});
console.log(nile.api.headers);