reference.md

API Reference

• Permit
  • permit.check
  • permit.fail
• Types
  • Basic
  • Bearer
  • Permit

Permit

Each permit instance has two methods, check and fail...

permit.check

permit.check(req) => credentials

const credentials = permit.check(req)

The check method takes a Node.js req object and checks it for credentials based on the permit's configuration, returning any credentials it finds.

It does not dictate how the credentials should be validated.

permit.fail

permit.fail(res) => undefined

if (!credentials) {
  permit.fail(res)
  throw new Error()
}

The fail method takes a Node.js res object and augments it with authentication-specific HTTP headers that browsers and other clients expect, so that consumers can know what types of authentication are expected.

It does not dictate what the error response to the client should be.

Types

The following permit types come packaged with the library...

import { Basic, Bearer, Permit } from 'permit'

Basic

import { Basic } from 'permit'

const permit = new Basic()

The Basic permit checks for credentials in the form of username and password strings, in the form of HTTP Basic Auth.

Bearer

import { Bearer } from 'permit'

const permit = new Bearer({
  basic: String,
  header: String,
  query: String,
})

The Bearer permit checks for credentials in the form of a secret bearer token string. This can either be via HTTP Bearer Auth, via HTTP Basic Auth, or via a query string.

• basic — Either 'username' or 'password' denoting which field of the HTTP Basic Auth to use as a fallback.
• header — A custom header key to check as a fallback.
• query — A query parameter key to check as a fallback.

Permit

The generic Permit is provided to be extended by other permits, in case you need to implement custom checking logic.