Version: 2.x (Latest)

Functions

@authorizerdev/authorizer-js SDK comes with bunch of utility functions, that you can use to perform various operations without worrying about the API details.

Table of Contents

authorize
getToken
login
signup
verifyEmail
getProfile
updateProfile
forgotPassword
resetPassword
oauthLogin
magicLinkLogin
getMetadata
getSession
revokeToken
logout
validateJWTToken
validateSession
checkPermissions
listPermissions
verifyOtp
resendOtp
deactivateAccount

These functions can be invoked using the Authorizer instance:

const authRef = new Authorizer({
  authorizerURL: 'YOUR_AUTHORIZER_INSTANCE_URL',
  redirectURL: window.location.origin,
  clientID: 'YOUR_CLIENT_ID',
})

- `authorize`

Function to auto login from browser using the builtin UI of authorizer. It checks for session, if available returns the token information, else redirects to login page.

It supports PKCE flow. This will help user to perform authentication and authorization in safe memory and prevent from CSRF attack. It also enables perform authorization with safety on mobile applications (Tried and tested with Expo AuthSession)
It supports Implicit Flow

It accepts JSON object as a parameter with following keys

Key	Description	Required
`response_type`	What type of response you want. It supports `code` & `token` as response types. Default value is `token`	false
`response_mode`	Response is required in which format. Supports 2 forms `query` (returns redirect url with response in query string) and `web_message` (returns html page with data embedded in JS). Default its value is `query`	false
`use_refresh_token`	Whether to include refresh token in response or not	false

If session exists following keys are returned in data object.

Response

Key	Description
`access_token`	accessToken that frontend application can use for further authorized requests
`expires_in`	timestamp when the current token is going to expire, so that frontend can request for new access token
`id_token`	JWT token holding the user information
`refresh_token`	When scope includes `offline_access`, Long living token is returned which can be used to get new access tokens. This is rotated with each request

Sample Usage

const { data, errors } = await authRef.authorize({
  response_type: 'code',
  response_mode: 'query',
})

- `getToken`

Function to get token information based on code / refresh_token

It accepts JSON object as a parameter with following keys

Key	Description	Required
`grant_type`	Supports `authorization_code` & `refresh_token` grant types. Default is `authorization_code`	false
`code_verifier`	Code verifier to verify against the code_challenge sent in authorize request. Required if `authorization_code` flow is used.	false
`code`	Code returned form authorize request is sent to make sure it is follow up of same request	false
`refresh_token`	Refresh token used to get the new access token. Required in case of `refresh_token` grant type	false

If session exists following keys are returned in the data object.

Response

Key	Description
`access_token`	accessToken that frontend application can use for further authorized requests
`expires_in`	timestamp when the current token is going to expire, so that frontend can request for new access token
`id_token`	JWT token holding the user information
`refresh_token`	When scope includes `offline_access`, Long living token is returned which can be used to get new access tokens. This is rotated with each request

Sample Usage

// for web apps
const { data, errors } = await authRef.getToken({
  response_type: 'code',
  response_mode: 'query',
})

// for mobile applications / desktop apps
const { data, errors } = await authRef.getToken({
  grant_type: 'refresh_token',
  refresh_token:
    'your refresh_token from login (should store in memmory such as store, variables)',
})

- `signup`

Function to sign-up user using email and password.

It accepts JSON object as a parameter with the following keys

Key	Description	Required
`email`	Email address of user	true
`password`	Password that user wants to set	true
`confirm_password`	Value same as password to make sure that its user and not robot	true
`given_name`	First name of the user	false
`family_name`	Last name of the user	false
`picture`	Profile picture URL	false
`roles`	Array of string with valid roles. Defaults to `[user]` if not configured	false
`middle_name`	middle name of user	false
`nickname`	nick name of user	false
`gender`	gender of user	false
`birthdate`	birthdate of user	false
`phone_number`	phone number of user	false
`redirect_uri`	URL where user should be redirected after login	false
`scope`	List of openID scopes. If not present default scopes ['openid', 'email', 'profile', 'offline_access'] is used	false

Following is the response for the signup in the data object

Response

Key	Description
`message`	Success / Error message from server
`access_token`	accessToken that frontend application can use for further authorized requests
`expires_in`	timestamp when the current token is going to expire, so that frontend can request for new access token
`id_token`	JWT token holding the user information
`refresh_token`	When scope includes `offline_access`, Long living token is returned which can be used to get new access tokens. This is rotated with each request
`user`	User object with its profile keys mentioned above. This is only returned if `DISABLE_EMAIL_NOTIFICATION` is set to `true` in environment variables
`should_show_email_otp_screen`	Is set to true if email based multi factor authentication is enabled
`should_show_mobile_otp_screen`	Is set to true if mobiled based multi factor authentication is enabled
`should_show_totp_screen`	Is set to true if totp based multi factor authentication is enabled
`authenticator_scanner_image`	If totp registration is pending it sends base64 encoded image string that can be rendered by totp app scanners like Google Authentication
`authenticator_secret`	If totp registration is pending, then this secret can be used for registration instead of image on authenticator apps
`authenticator_recovery_codes`	If totp registration is pending, then recovery codes are sent using which totp can be accessed again

Sample Usage

const { data, errors } = await authRef.signup({
  email: 'foo@bar.com',
  password: 'test',
  confirm_password: 'test',
  scope: ['offline_access'], // for refresh token
})

- `login`

Function to login user using email and password.

It accepts JSON object as a parameter with the following keys

Key	Description	Required
`email`	Email address of user	true
`password`	Password of user	true
`roles`	Roles of user that he/she wants to login with. It accepts array of string. Defaults to `[user]` role if not configured	false
`scope`	List of openID scopes. If not present default scopes ['openid', 'email', 'profile'] is used	false

Following is the response for login in the data object

Response

Key	Description
`message`	Error / Success message from server
`access_token`	accessToken that frontend application can use for further authorized requests
`expires_in`	timestamp when the current token is going to expire, so that frontend can request for new access token
`id_token`	JWT token holding the user information
`refresh_token`	When scope includes `offline_access`, Long living token is returned which can be used to get new access tokens. This is rotated with each request
`user`	User object with all the basic profile information
`should_show_email_otp_screen`	Is set to true if email based multi factor authentication is enabled
`should_show_mobile_otp_screen`	Is set to true if mobiled based multi factor authentication is enabled
`should_show_totp_screen`	Is set to true if totp based multi factor authentication is enabled
`authenticator_scanner_image`	If totp registration is pending it sends base64 encoded image string that can be rendered by totp app scanners like Google Authentication
`authenticator_secret`	If totp registration is pending, then this secret can be used for registration instead of image on authenticator apps
`authenticator_recovery_codes`	If totp registration is pending, then recovery codes are sent using which totp can be accessed again

Sample Usage

const { data, errors } = await authRef.login({
  email: 'foo@bar.com',
  password: 'test',
})

- `verifyEmail`

Function to verify email address of user when they signup.

It accepts JSON object as a parameter with following keys

Key	Description	Required
`token`	Token sent for verifying user	true

This mutation returns AuthResponse type with the following keys in the data object

Response

Key	Description
`message`	Success / Error message from server
`should_show_email_otp_screen`	Boolean value for frontend application to show otp input for email based login screen
`should_show_mobile_otp_screen`	Boolean value for frontend application to show otp input for mobile based login screen
`access_token`	accessToken that frontend application can use for further authorized requests
`expires_in`	timestamp when the current token is going to expire, so that frontend can request for new access token
`id_token`	JWT token holding the user information
`refresh_token`	When scope includes `offline_access`, Long living token is returned which can be used to get new access tokens. This is rotated with each request
`user`	User object with its profile keys mentioned above.
`should_show_email_otp_screen`	Is set to true if email based multi factor authentication is enabled
`should_show_mobile_otp_screen`	Is set to true if mobiled based multi factor authentication is enabled
`should_show_totp_screen`	Is set to true if totp based multi factor authentication is enabled
`authenticator_scanner_image`	If totp registration is pending it sends base64 encoded image string that can be rendered by totp app scanners like Google Authentication
`authenticator_secret`	If totp registration is pending, then this secret can be used for registration instead of image on authenticator apps
`authenticator_recovery_codes`	If totp registration is pending, then recovery codes are sent using which totp can be accessed again

Sample Usage

const { data, errors } = await authRef.verifyEmail({
  token: `some_token`,
})

- `getProfile`

Function to get profile of user. This function makes an authorized request, hence if it is used from the browser the HTTP cookie is sent if user has logged in else you need to pass headers object.

It accepts the optional JSON object as parameter, you can pass the HTTP Headers there.

Key	Description	Required
`Authorization`	Authorization header passed to the server. It needs `Bearer access_token` as its value	true

It returns the following keys in response data object

Response

Key	Description
`id`	user unique identifier
`email`	email address of user
`given_name`	first name of user
`family_name`	last name of user
`signup_methods`	methods using which user have signed up, eg: `google,github`
`email_verified`	determine if email is verified or not
`picture`	profile picture URL
`roles`	user roles
`created_at`	timestamp at which the user entry was created
`updated_at`	timestamp at which the user entry was updated

Sample Usage

// from browser if HTTP cookie is present
const { data, errors } = await authRef.getProfile()

// from NodeJS / if HTTP cookie is not used
const { data, errors } = await authRef.getProfile({
  Authorization: `Bearer ${token}`,
})

- `updateProfile`

Function to update profile of user. This function makes an authorized request, hence if it is used from the browser the HTTP cookie is sent if user has logged in else you need to pass headers object.

It accepts 2 JSON object as its parameters.

data - User data that needs to be updated
headers - To pass Authorization header

Here are the keys that data object accepts

Key	Description	Required
`given_name`	New first name of the user	false
`family_name`	New last name of the user	false
`email`	New email of th user. This will logout the user and send the new verification mail to user if `DISABLE_EMAIL_NOTIFICATION` is set to false	false
`old_password`	In case if user wants to change password they need to specify the older password here. In this scenario `newPassword` and `confirmNewPassword` will be required.	false
`newPassword`	New password that user wants to set. In this scenario `old_password` and `confirmNewPassword` will be required	false
`confirmNewPassword`	Value same as the new password to make sure it matches the password entered by user. In this scenario `old_password` and `newPassword` will be required	false

Here is sample of headers object

Key	Description	Required
`Authorization`	Authorization header passed to the server. It needs `Bearer access_token` as its value	true

It returns the following keys in response data object

Response

Key	Description
`message`	Success / Error message from server

Sample Usage

const { data, errors } = await authRef.updateProfile(
  {
    given_name: `bob`,
  },
  {
    Authorization: `Bearer some_token`,
  },
)

- forgotPassword

Function that can be used in case if user has forgotten their password. Forgot password is 2 step process.

Step 1: Send email to registered user Step 2: Reset password.

This function is Step 1 process.

It accepts JSON object as parameter with the following keys

Note: You will need a SMTP server with an email address and password configured as authorizer environment using which system can send emails.

Key	Description	Required
`email`	Email for which password needs to be changed	true

It returns the following keys in response data object

Response

Key	Description
`message`	Success / Error message from server
`should_show_mobile_otp_screen`	Show OTP screen if mobile login is used

Sample Usage

const { data, errors } = await authRef.forgotPassword({
  email: 'foo@bar.com',
})

- `resetPassword`

Function to reset password. This is the step 2 of forgot password process.

It accepts JSON object as a parameter with following keys

Key	Description	Required
`token`	Token sent to the user in step 1.	true

It returns the following keys in response data object

Response

Key	Description
`message`	Success / Error message from server

Sample Usage

const { data, errors } = await authRef.resetPassword({
  token: `some_token`,
})

- `oauthLogin`

Function to login using OAuth Providers. This is mainly used in browser as user is redirect to respective oauth platform.

Note only enabled oauth providers can be used here. To get the information about enabled oauth provider you can use getMetadata function

It supports optional argument for role based login

Sample Usage

await authRef.oauthLogin('google')

// login with specific role
await authRef.oauthLogin('google', 'admin')

- magicLinkLogin

Function to perform password less login.

Note: You will need a SMTP server with an email address and password configured as authorizer environment using which system can send emails.

Key	Description	Required
`email`	Email using which user needs to login	true
`roles`	List of valid valid roles using which user needs to login	false
`scope`	List of openID scopes. If not present default scopes ['openid', 'email', 'profile'] is used	false
`redirect_uri`	URL where user should be redirected after login	false

It returns the following keys in response data object

Response

Key	Description
`message`	Success / Error message from server

Sample Usage

const { data, errors } = await authRef.magicLinkLogin({
  email: 'foo@bar.com',
})

- `getMetadata`

Function to get meta information about your authorizer instance. eg, version, configurations, etc

It returns the following keys in response data object

Response

Key	Description
`version`	Authorizer version that is currently deployed
`client_id`	Identifier of your instance
`is_google_login_enabled`	It gives information if google login is configured or not
`is_github_login_enabled`	It gives information if github login is configured or not
`is_facebook_login_enabled`	It gives information if facebook login is configured or not
`is_email_verification_enabled`	It gives information if email verification is enabled or not
`is_basic_authentication_enabled`	It gives information, if basic auth is enabled or not
`is_magic_link_login_enabled`	It gives information if password less login is enabled or not

Sample Usage

const { data, errors } await authRef.getMetadata()

- `getSession`

Function to get session information. This function makes an authorized request, hence if it is used from the browser the HTTP cookie is sent if user has logged in else you need to pass headers object.

It accepts the optional JSON object as parameter, you can pass the HTTP Headers there. Optionally you can also pass a SessionQueryRequest object as the second argument to validate roles against the session.

Key	Description	Required
`Authorization`	Authorization header passed to the server. It needs `Bearer some_token` as its value	false

It returns the following keys in response data object

Response

Key	Description
`message`	Error / Success message from server
`access_token`	accessToken that frontend application can use for further authorized requests
`expires_in`	timestamp when the current token is going to expire, so that frontend can request for new access token
`user`	User object with all the basic profile information
`should_show_email_otp_screen`	Is set to true if email based multi factor authentication is enabled
`should_show_mobile_otp_screen`	Is set to true if mobiled based multi factor authentication is enabled
`should_show_totp_screen`	Is set to true if totp based multi factor authentication is enabled
`authenticator_scanner_image`	If totp registration is pending it sends base64 encoded image string that can be rendered by totp app scanners like Google Authentication
`authenticator_secret`	If totp registration is pending, then this secret can be used for registration instead of image on authenticator apps
`authenticator_recovery_codes`	If totp registration is pending, then recovery codes are sent using which totp can be accessed again

Sample Usage

// from browser with HTTP Cookie
const { data, errors } = await authRef.getSession()

// role validation with http cookie
const { data, errors } = await authRef.getSession(null, 'admin')

// from NodeJS / if HTTP cookie is not used
const { data, errors } = await authRef.getSession(
  {
    Authorization: `Bearer some_token`,
  },
  'admin',
)

- `revokeToken`

Function to revoke refresh token. It accepts json object as its parameter with following keys

JSON Object

Key	Description	Required
`refresh_token`	Refresh token to be revoked	true

It returns the following keys in response data object

Response

Key	Description
`message`	Success message

Sample Usage

const { data, errors } = await authRef.revokeToken({
  refresh_token: 'foo',
})

- `logout`

Function to logout user. This function makes an authorized request, hence if it is used from the browser the HTTP cookie is sent if user has logged in else you need to pass headers object.

It accepts the optional JSON object as parameter, you can pass the HTTP Headers there.

Key	Description	Required
`Authorization`	Authorization header passed to the server. It needs `Bearer some_token` as its value	false

It returns the following keys in response data object

Response

Key	Description
`message`	Success / Error message from server

Sample Usage

// from browser with HTTP Cookie
const { data, errors } = await authRef.logout()

// from NodeJS / if HTTP cookie is not used
const { data, errors } = await authRef.logout({
  Authorization: `Bearer some_token`,
})

- `validateJWTToken`

Function to validate jwt tokens.

It expects the JSON object as parameter with following parameters

Key	Description	Required
`token_type`	Type of token that needs to be validated. It can be one of `access_token`, `refresh_token` or `id_token`	`true`
`token`	Jwt token string	`true`
`roles`	Array of roles to validate jwt token for	`false`

It returns the following keys in response data object

Response

Key	Description
`is_valid`	Boolean indicating if given token was valid or not

Sample Usage

const { data, errors } = await authRef.validateJWTToken({
  token_type: `access_token`,
  token: `some jwt token string`,
})

- `validateSession`

Function to validate cookie / browser session.

It expects the JSON object as parameter with following parameters

Key	Description	Required
`cookie`	browser session cookie value. If not present it will need coookie present in header as https cookie	`false`
`roles`	Array of roles to validate jwt token for	`false`

It returns the following keys in response data object

Response

Key	Description
`is_valid`	Boolean indicating if given token was valid or not

Sample Usage

const { data, errors } = await authRef.validateSession({
  cookie: ``,
})

- `checkPermissions`

Function to evaluate one or more fine-grained authorization (FGA) permission checks against the embedded OpenFGA engine, in a single call. results come back in the same order as checks and echo each pair.

This function makes an authorized request, hence from the browser the HTTP cookie is sent automatically if the user has logged in. From NodeJS pass the Authorization header as the optional second argument.

The subject defaults to the caller's token. An optional user ("type:id", or a bare id treated as user:<id>) is honored only for super-admins or when it equals the caller's own token subject; anything else is rejected by the server — never silently ignored.

For complete worked scenarios — Express middleware, list filtering, and tuple lifecycle — see Authorization recipes.

It accepts 2 JSON objects as its parameters.

data - Permission checks to evaluate
headers - To pass Authorization header (optional in the browser)

Here are the keys that the data object accepts

Key	Description	Required
`checks`	Array of checks, each `{ relation, object, contextual_tuples? }`. `contextual_tuples` (array of `{ user, relation, object }`) are evaluated for that check only and never persisted	true
`user`	Subject override ("type:id", or a bare id treated as `user:<id>`). Honored only for super-admins or self; defaults to the caller	false

It returns the following keys in response data object

Response

Key	Description
`results`	One result per supplied check, in order, each `{ relation, object, allowed }` echoing the checked pair

Sample Usage

const { data, errors } = await authRef.checkPermissions(
  {
    checks: [
      { relation: 'can_view', object: 'document:1' },
      { relation: 'can_edit', object: 'document:1' },
    ],
  },
  { Authorization: `Bearer ${token}` }, // omit in the browser to use the cookie
);

if (data?.results?.[0]?.allowed) {
  // caller may view document:1
}

// "What-if" check with contextual tuples (evaluated for this call only):
const { data: whatIf } = await authRef.checkPermissions(
  {
    checks: [
      {
        relation: 'can_view',
        object: 'document:1',
        contextual_tuples: [
          { user: 'user:1b9d…', relation: 'viewer', object: 'document:1' },
        ],
      },
    ],
  },
  { Authorization: `Bearer ${token}` },
);

- `listPermissions`

Function to list what the subject can access — ideal for filtering a list page down to what the user may see. With both relation and object_type set it answers "which object_types can I relation?"; either or both filters may be omitted, so an empty data object returns every permission the subject holds. Subject resolution follows the same rules as checkPermissions.

It accepts 2 JSON objects as its parameters.

data - Optional relation / object type filters
headers - To pass Authorization header (optional in the browser)

Here are the keys that the data object accepts

Key	Description	Required
`relation`	Relation to list for (e.g. `can_view`). Omit to enumerate every relation of the active model	false
`object_type`	Object type to enumerate (e.g. `document`). Omit to enumerate every type of the active model	false
`user`	Subject override ("type:id", or a bare id treated as `user:<id>`). Honored only for super-admins or self	false

It returns the following keys in response data object

Response

Key	Description
`objects`	Distinct fully-qualified ids of the objects the subject holds the relation on, e.g. `["document:1"]`
`permissions`	The `(object, relation)` detail behind `objects` — relevant when no `relation` filter was supplied
`truncated`	`true` when the result was capped (1000 entries) and more permissions exist

Sample Usage

const { data, errors } = await authRef.listPermissions(
  { relation: 'can_view', object_type: 'document' },
  { Authorization: `Bearer ${token}` },
);
// data?.objects => ['document:1', 'document:7', ...]

// No filters: everything the caller holds, with per-relation detail
const all = await authRef.listPermissions({}, { Authorization: `Bearer ${token}` });
// all.data?.permissions => [{ object: 'document:1', relation: 'can_view' }, ...]
// all.data?.truncated => false

- `verifyOtp`

Function to verify OTP sent to the user when they login.

It accepts JSON object as a parameter with following keys

Key	Description	Required
`email`	Email address of user	false
`phone_number`	Phone number of user	false
`otp`	OTP (One Time Password) sent to user email address	true

Either email or phone_number is required

It returns the following keys in response data object

Response

Key	Description
`message`	Error / Success message from server
`access_token`	accessToken that frontend application can use for further authorized requests
`expires_in`	timestamp when the current token is going to expire, so that frontend can request for new access token
`id_token`	JWT token holding the user information
`refresh_token`	When scope includes `offline_access`, Long living token is returned which can be used to get new access tokens. This is rotated with each request
`user`	User object with all the basic profile information
`should_show_email_otp_screen`	Is set to true if email based multi factor authentication is enabled
`should_show_mobile_otp_screen`	Is set to true if mobiled based multi factor authentication is enabled
`should_show_totp_screen`	Is set to true if totp based multi factor authentication is enabled
`authenticator_scanner_image`	If totp registration is pending it sends base64 encoded image string that can be rendered by totp app scanners like Google Authentication
`authenticator_secret`	If totp registration is pending, then this secret can be used for registration instead of image on authenticator apps
`authenticator_recovery_codes`	If totp registration is pending, then recovery codes are sent using which totp can be accessed again

Sample Usage

const { data, errors } = await authRef.verifyOtp({
  email: 'foo@bar.com',
  otp: 'AB123C',
})

- `resendOtp`

Function to resend OTP to the user.

It accepts JSON object as a parameter with following keys

Key	Description	Required
`email`	Email address of user	false
`phone_number`	Phone number of user	false

Either email or phone_number is required

It returns the following keys in response data object

Response

Key	Description
`message`	Error / Success message from server

Sample Usage

const { data, errors } = await authRef.resendOtp({
  email: 'foo@bar.com',
})

- `deactivateAccount`

Function to deactivate user account. This function makes an authorized request, hence if it is used from the browser the HTTP cookie is sent if user has logged in else you need to pass headers object.

It accepts 1 JSON object as its parameters.

headers - To pass Authorization header

Here is sample of headers object

Key	Description	Required
`Authorization`	Authorization header passed to the server. It needs `Bearer access_token` as its value	true

It returns the following keys in response data object

Response

Key	Description
`message`	Success / Error message from server

Sample Usage

const { data, errors } = await authRef.deactivateAccount({
  Authorization: `Bearer some_token`,
})

- authorize​

- getToken​

- signup​

- login​

- verifyEmail​

- getProfile​

- updateProfile​

- forgotPassword​

- resetPassword​

- oauthLogin​

- magicLinkLogin​

- getMetadata​

- getSession​

- revokeToken​

- logout​

- validateJWTToken​

- validateSession​

- checkPermissions​

- listPermissions​

- verifyOtp​

- resendOtp​

- deactivateAccount​

- `authorize`

- `getToken`

- `signup`

- `login`

- `verifyEmail`

- `getProfile`

- `updateProfile`

- forgotPassword

- `resetPassword`

- `oauthLogin`

- magicLinkLogin

- `getMetadata`

- `getSession`

- `revokeToken`

- `logout`

- `validateJWTToken`

- `validateSession`

- `checkPermissions`

- `listPermissions`

- `verifyOtp`

- `resendOtp`

- `deactivateAccount`