Version: 🚧 Canary

📐 Authentication schemas

Schemas define endpoint validation and OpenAPI metadata. Start with the setup and HTTP workflow, then use this page to confirm the exact request contract. The matching feature composes each schema and route; use cookie utilities for transport-specific refresh and logout behavior.

Inventory

Export	Request location	Contract
`passwordSchema`	N/A	Reusable password object with the SDK password pattern.
`providerSchema`	N/A	Reusable `provider` and `providerId` object.
`credentialsSchema`	N/A	Reusable email/password credential object.
`identitySchema`	Body	Credential or provider identity JSON.
`loginWithCredentialsSchema`	Body	Credential login with optional body fingerprint.
`resendMfaCodeSchema`	Body	MFA challenge token.
`verifyMfaCodeSchema`	Body	MFA challenge token and code.
`loginWithOnetimeTokenSchema`	Body	One-time login token.
`registerCredentialsSchema`	Body	Registration credentials and optional invitation token.
`sendVerificationEmailSchema`	Path, body	Identity ID and optional body fingerprint.
`confirmEmailSchema`	Body	Email-confirmation token.
`changeEmailSchema`	Path, body	Identity ID and new email; source header parameters are commented out.
`checkTokenSchema`	Body	Token and optional expected target.
`confirmNewEmailSchema`	Body	Email-change token; source header parameters are commented out.
`sendResetPasswordLinkEmailSchema`	Body	Email; source header parameters are commented out.
`completePasswordResetSchema`	Body	Replacement password; runtime needs an Authorization header that the schema does not validate.
`changePasswordSchema`	Path, body	Identity ID, current password, and replacement password.
`deactivateSchema`	Body	Identity ID to deactivate.
`activateSchema`	Body	Identity ID to activate.
`refreshTokenCookieSchema`	Body	Empty cookie-mode refresh body.
`refreshTokenBearerSchema`	Body	Bearer-mode refresh token.
`refreshTokenSchema`	Body	Deprecated alias of `refreshTokenBearerSchema`.
`logoutCookieSchema`	Body	Empty cookie-mode logout body.
`logoutBearerSchema`	Body	Bearer-mode refresh token used for logout.
`deleteRefreshTokensSchema`	Path	Identity ID whose refresh records are revoked.

View shared source context

import {OpenAPIParameter, SchemaDefinition, withSchema} from '../primitives';

const identityIdPathParameter: OpenAPIParameter = {
  in: 'path',
  name: 'identityId',
  required: true,
  schema: {
    type: 'string',
  },
};

const hostHeaderParameter: OpenAPIParameter = {
  in: 'header',
  name: 'host',
  required: true,
  schema: {
    type: 'string',
  },
};

const userAgentHeaderParameter: OpenAPIParameter = {
  in: 'header',
  name: 'user-agent',
  required: true,
  schema: {
    type: 'string',
  },
};

const fingerprintHeaderParameter: OpenAPIParameter = {
  in: 'header',
  name: 'x-nb-fingerprint',
  required: false,
  schema: {
    type: 'string',
  },
};

const authorizationHeaderParameter: OpenAPIParameter = {
  in: 'header',
  name: 'Authorization',
  required: true,
  schema: {
    type: 'string',
  },
};

const defaultPasswordPattern = '^(?=.*[a-z])(?=.*[0-9])[A-Za-z0-9.?/_-]{8,24}$';

Details

`passwordSchema`

Definition

Reusable object with additionalProperties: false. Field: password is an optional string matching ^(?=.*[a-z])(?=.*[0-9])[A-Za-z0-9.?/_-]{8,24}$. It is spread by completePasswordResetSchema; no route or feature composes it directly.

View complete source

export const passwordSchema: SchemaDefinition = {
  $schema: 'http://json-schema.org/draft-07/schema#',
  additionalProperties: false,
  properties: {
    password: {
      pattern: defaultPasswordPattern,
      type: 'string',
    },
  },
  type: 'object',
};

`providerSchema`

Definition

Reusable object with additionalProperties: false. Fields: optional string provider and optional string providerId; the reusable definition has no required array. It is spread by identitySchema; no route or feature composes it directly.

View complete source

export const providerSchema: SchemaDefinition = {
  $schema: 'http://json-schema.org/draft-07/schema#',
  additionalProperties: false,
  properties: {
    provider: {type: 'string'},
    providerId: {type: 'string'},
  },
  type: 'object',
};

`credentialsSchema`

Definition

Reusable object with additionalProperties: false. Fields, in source order: required string email, optional boolean emailVerified with default false, and required string password. It is spread by identitySchema; no route or feature composes it directly.

View complete source

export const credentialsSchema: SchemaDefinition = {
  $schema: 'http://json-schema.org/draft-07/schema#',
  additionalProperties: false,
  properties: {
    email: {type: 'string'},
    emailVerified: {default: false, type: 'boolean'},
    password: {type: 'string'},
  },
  required: ['email', 'password'],
  type: 'object',
};

`identitySchema`

Definition

Required application/json body intended to accept either email plus password or provider plus providerId, with no additional properties. Because source spreads the complete credentialsSchema and then providerSchema, the latter overwrites duplicate top-level keys including properties; this export is currently not composed by an Authentication feature or route.

View complete source

export const identitySchema = withSchema({
  requestBody: {
    content: {
      'application/json': {
        schema: {
          ...credentialsSchema,
          ...providerSchema,
          oneOf: [{required: ['email', 'password']}, {required: ['provider', 'providerId']}],
          required: [],
        },
      },
    },
    required: true,
  },
});

`loginWithCredentialsSchema`

Definition

Required application/json body with additionalProperties: false: required string email, optional string fingerprint, and required string password. Used by route: loginWithCredentialsRoute. Used by feature: loginWithCredentialsFeature.

View complete source

export const loginWithCredentialsSchema = withSchema({
  requestBody: {
    content: {
      'application/json': {
        schema: {
          $schema: 'http://json-schema.org/draft-07/schema#',
          additionalProperties: false,
          properties: {
            email: {type: 'string'},
            fingerprint: {type: 'string'},
            password: {type: 'string'},
          },
          required: ['email', 'password'],
          type: 'object',
        },
      },
    },
    required: true,
  },
});

`resendMfaCodeSchema`

Definition

Required application/json body with additionalProperties: false and one required string field, token. Used by route: resendMfaCodeRoute. Used by feature: resendMfaCodeFeature.

View complete source

export const resendMfaCodeSchema = withSchema({
  requestBody: {
    content: {
      'application/json': {
        schema: {
          $schema: 'http://json-schema.org/draft-07/schema#',
          additionalProperties: false,
          properties: {
            token: {
              type: 'string',
            },
          },
          required: ['token'],
          type: 'object',
        },
      },
    },
    required: true,
  },
});

`verifyMfaCodeSchema`

Definition

Required application/json body with additionalProperties: false: required string code, then required string token in source property order; the required array is ['token', 'code']. Used by route: verifyMfaCodeRoute. Used by feature: verifyMfaCodeFeature.

View complete source

export const verifyMfaCodeSchema = withSchema({
  requestBody: {
    content: {
      'application/json': {
        schema: {
          $schema: 'http://json-schema.org/draft-07/schema#',
          additionalProperties: false,
          properties: {
            code: {type: 'string'},
            token: {type: 'string'},
          },
          required: ['token', 'code'],
          type: 'object',
        },
      },
    },
    required: true,
  },
});

`loginWithOnetimeTokenSchema`

Definition

Required application/json body with additionalProperties: false and required string token. Used by route: loginWithOnetimeTokenRoute. Used by feature: loginWithOnetimeTokenFeature.

View complete source

export const loginWithOnetimeTokenSchema = withSchema({
  requestBody: {
    content: {
      'application/json': {
        schema: {
          $schema: 'http://json-schema.org/draft-07/schema#',
          additionalProperties: false,
          properties: {
            token: {type: 'string'},
          },
          required: ['token'],
          type: 'object',
        },
      },
    },
    required: true,
  },
});

`registerCredentialsSchema`

Definition

Required application/json body with additionalProperties: false. String fields are email, password, and token; password is always required and oneOf additionally requires either email plus password or token plus password. Used by route: registerCredentialsRoute. Used by feature: registerCredentialsFeature.

View complete source

export const registerCredentialsSchema = withSchema({
  requestBody: {
    content: {
      'application/json': {
        schema: {
          $schema: 'http://json-schema.org/draft-07/schema#',
          additionalProperties: false,
          oneOf: [{required: ['email', 'password']}, {required: ['token', 'password']}],
          properties: {
            email: {type: 'string'},
            password: {type: 'string'},
            token: {type: 'string'},
          },
          required: ['password'],
          type: 'object',
        },
      },
    },
    required: true,
  },
});

`sendVerificationEmailSchema`

Definition

Required string path parameter identityId plus a required application/json body that allows only optional string fingerprint; the body object itself is required. Used by route: sendVerificationEmailRoute. Used by feature: emailVerificationFeature.

View complete source

export const sendVerificationEmailSchema = withSchema({
  parameters: [{...identityIdPathParameter}],
  requestBody: {
    content: {
      'application/json': {
        schema: {
          $schema: 'http://json-schema.org/draft-07/schema#',
          additionalProperties: false,
          properties: {
            fingerprint: {type: 'string'},
          },
          type: 'object',
        },
      },
    },
    required: true,
  },
});

`confirmEmailSchema`

Definition

Required application/json body with additionalProperties: false and required string token. Used by route: confirmEmailRoute. Used by feature: confirmEmailFeature.

View complete source

export const confirmEmailSchema = withSchema({
  requestBody: {
    content: {
      'application/json': {
        schema: {
          $schema: 'http://json-schema.org/draft-07/schema#',
          additionalProperties: false,
          properties: {
            token: {type: 'string'},
          },
          required: ['token'],
          type: 'object',
        },
      },
    },
    required: true,
  },
});

`changeEmailSchema`

Definition

Required string path parameter identityId and required application/json body with no additional properties. Body field email is a required string with minLength: 1 and pattern \S. Host, user-agent, and fingerprint parameters are commented out and are not schema-enforced. Used by route: changeEmailRoute. Used by feature: changeEmailFeature.

View complete source

export const changeEmailSchema = withSchema({
  parameters: [
    {...identityIdPathParameter},
    // TODO: uncomment when withSchema can accept headers
    // { ...hostHeaderParameter },
    // { ...userAgentHeaderParameter },
    // { ...fingerprintHeaderParameter },
  ],
  requestBody: {
    content: {
      'application/json': {
        schema: {
          $schema: 'http://json-schema.org/draft-07/schema#',
          additionalProperties: false,
          properties: {
            email: {minLength: 1, pattern: '\\S', type: 'string'},
          },
          required: ['email'],
          type: 'object',
        },
      },
    },
    required: true,
  },
});

`checkTokenSchema`

Definition

Required application/json body with additionalProperties: false: optional string target followed by required string token. Used by route: checkTokenRoute. Used by feature: checkTokenFeature.

View complete source

export const checkTokenSchema = withSchema({
  requestBody: {
    content: {
      'application/json': {
        schema: {
          $schema: 'http://json-schema.org/draft-07/schema#',
          additionalProperties: false,
          properties: {
            target: {type: 'string'},
            token: {type: 'string'},
          },
          required: ['token'],
          type: 'object',
        },
      },
    },
    required: true,
  },
});

`confirmNewEmailSchema`

Definition

application/json body allowing only required string token; the request body wrapper itself is not marked required. Host, user-agent, and fingerprint parameters are commented out. Used by route: confirmNewEmailRoute. Used by feature: confirmNewEmailFeature.

View complete source

export const confirmNewEmailSchema = withSchema({
  // TODO: uncomment when withSchema can accept headers
  // parameters: [
  //   // { ...hostHeaderParameter },
  //   // { ...userAgentHeaderParameter },
  //   // { ...fingerprintHeaderParameter },
  // ],
  requestBody: {
    content: {
      'application/json': {
        schema: {
          $schema: 'http://json-schema.org/draft-07/schema#',
          additionalProperties: false,
          properties: {token: {type: 'string'}},
          required: ['token'],
          type: 'object',
        },
      },
    },
  },
});

`sendResetPasswordLinkEmailSchema`

Definition

application/json body allowing only required string email with minLength: 1 and pattern \S; the request body wrapper itself is not marked required. Host, user-agent, and fingerprint parameters are commented out. Used by route: sendResetPasswordLinkEmailRoute. Used by feature: sendResetPasswordLinkEmailFeature.

View complete source

export const sendResetPasswordLinkEmailSchema = withSchema({
  // TODO: uncomment when withSchema can accept headers
  // parameters: [
  //   // { ...hostHeaderParameter },
  //   // { ...userAgentHeaderParameter },
  //   // { ...fingerprintHeaderParameter },
  // ],
  requestBody: {
    content: {
      'application/json': {
        schema: {
          $schema: 'http://json-schema.org/draft-07/schema#',
          additionalProperties: false,
          properties: {
            email: {minLength: 1, pattern: '\\S', type: 'string'},
          },
          required: ['email'],
          type: 'object',
        },
      },
    },
  },
});

`completePasswordResetSchema`

Definition

application/json body spreads passwordSchema and makes password required. The source declares an empty parameters array because host, user-agent, fingerprint, and Authorization entries are commented out; runtime still reads the reset token from Authorization: Bearer <token>. Used by route: completePasswordResetRoute. Used by feature: completePasswordResetFeature.

View complete source

export const completePasswordResetSchema = withSchema({
  // TODO: uncomment when withSchema can accept headers
  parameters: [
    // { ...hostHeaderParameter },
    // { ...userAgentHeaderParameter },
    // { ...fingerprintHeaderParameter },
    // { ...authorizationHeaderParameter },
  ],
  requestBody: {
    content: {
      'application/json': {
        schema: {
          ...passwordSchema,
          required: ['password'],
        },
      },
    },
  },
});

`changePasswordSchema`

Definition

Required string path parameter identityId. The application/json body has no additional properties and requires password (nonempty string matching \S) and newPassword (string matching the default password pattern); the body wrapper is not marked required. Used by route: changePasswordRoute. Used by feature: changePasswordFeature.

View complete source

export const changePasswordSchema = withSchema({
  parameters: [{...identityIdPathParameter}],
  requestBody: {
    content: {
      'application/json': {
        schema: {
          $schema: 'http://json-schema.org/draft-07/schema#',
          additionalProperties: false,
          properties: {
            newPassword: {
              pattern: defaultPasswordPattern,
              type: 'string',
            },
            password: {minLength: 1, pattern: '\\S', type: 'string'},
          },
          required: ['password', 'newPassword'],
          type: 'object',
        },
      },
    },
  },
});

`deactivateSchema`

Definition

application/json body allowing only required string identityId with minLength: 1 and pattern \S; the body wrapper is not marked required. Host, user-agent, fingerprint, and Authorization parameters are commented out. Used by route: deactivateRoute. Used by feature: deactivateFeature.

View complete source

export const deactivateSchema = withSchema({
  parameters: [
    // { ...hostHeaderParameter },
    // { ...userAgentHeaderParameter },
    // { ...fingerprintHeaderParameter },
    // { ...authorizationHeaderParameter },
  ],
  requestBody: {
    content: {
      'application/json': {
        schema: {
          $schema: 'http://json-schema.org/draft-07/schema#',
          additionalProperties: false,
          properties: {
            identityId: {minLength: 1, pattern: '\\S', type: 'string'},
          },
          required: ['identityId'],
          type: 'object',
        },
      },
    },
  },
});

`activateSchema`

Definition

application/json body allowing only required string identityId with minLength: 1 and pattern \S; the body wrapper is not marked required. Used by route: activateRoute. Used by feature: activateFeature.

View complete source

export const activateSchema = withSchema({
  requestBody: {
    content: {
      'application/json': {
        schema: {
          $schema: 'http://json-schema.org/draft-07/schema#',
          additionalProperties: false,
          properties: {
            identityId: {minLength: 1, pattern: '\\S', type: 'string'},
          },
          required: ['identityId'],
          type: 'object',
        },
      },
    },
  },
});

`refreshTokenCookieSchema`

Definition

Optional application/json body whose schema is an object with no properties and additionalProperties: false. Used by route: refreshTokenRoute. Selected by feature: refreshTokenFeature when authMode is 'cookie'.

View complete source

export const refreshTokenCookieSchema = withSchema({
  requestBody: {
    content: {
      'application/json': {
        schema: {
          $schema: 'http://json-schema.org/draft-07/schema#',
          additionalProperties: false,
          properties: {},
          type: 'object',
        },
      },
    },
  },
});

`refreshTokenBearerSchema`

Definition

application/json body allowing only required string refreshToken; the body wrapper is not marked required. Header parameters are commented out. Used by route: refreshTokenRoute. Selected by feature: refreshTokenFeature outside cookie mode.

View complete source

export const refreshTokenBearerSchema = withSchema({
  // TODO: uncomment when withSchema can accept headers
  // parameters: [
  //   // { ...hostHeaderParameter },
  //   // { ...userAgentHeaderParameter },
  //   // { ...fingerprintHeaderParameter },
  // ],
  requestBody: {
    content: {
      'application/json': {
        schema: {
          $schema: 'http://json-schema.org/draft-07/schema#',
          additionalProperties: false,
          properties: {refreshToken: {type: 'string'}},
          required: ['refreshToken'],
          type: 'object',
        },
      },
    },
  },
});

`refreshTokenSchema`

Definition

Deprecated exact alias of refreshTokenBearerSchema. It adds no fields and is not composed by a current Authentication feature or route.

View complete source

export const refreshTokenSchema = refreshTokenBearerSchema;

`logoutCookieSchema`

Definition

Optional application/json body whose schema is an object with no properties and additionalProperties: false. Used by route: logoutRoute. Selected by feature: logoutFeature when authMode is 'cookie'.

View complete source

export const logoutCookieSchema = withSchema({
  requestBody: {
    content: {
      'application/json': {
        schema: {
          $schema: 'http://json-schema.org/draft-07/schema#',
          additionalProperties: false,
          properties: {},
          type: 'object',
        },
      },
    },
  },
});

`logoutBearerSchema`

Definition

application/json body allowing only required string refreshToken; the body wrapper is not marked required. Used by route: logoutRoute. Selected by feature: logoutFeature outside cookie mode.

View complete source

export const logoutBearerSchema = withSchema({
  requestBody: {
    content: {
      'application/json': {
        schema: {
          $schema: 'http://json-schema.org/draft-07/schema#',
          additionalProperties: false,
          properties: {refreshToken: {type: 'string'}},
          required: ['refreshToken'],
          type: 'object',
        },
      },
    },
  },
});

`deleteRefreshTokensSchema`

Definition

One required string path parameter, identityId. The commented host, user-agent, and fingerprint parameters are not schema-enforced. Used by route: deleteRefreshTokensRoute. Used by feature: deleteRefreshTokensFeature.

View complete source

export const deleteRefreshTokensSchema = withSchema({
  // TODO: uncomment when withSchema can accept headers
  // parameters: [
  //   // { ...hostHeaderParameter },
  //   // { ...userAgentHeaderParameter },
  //   // { ...fingerprintHeaderParameter },
  // ],

  parameters: [{...identityIdPathParameter}],
});

Inventory​

Details​

passwordSchema​

providerSchema​

credentialsSchema​

identitySchema​

loginWithCredentialsSchema​

resendMfaCodeSchema​

verifyMfaCodeSchema​

loginWithOnetimeTokenSchema​

registerCredentialsSchema​

sendVerificationEmailSchema​

confirmEmailSchema​

changeEmailSchema​

checkTokenSchema​

confirmNewEmailSchema​

sendResetPasswordLinkEmailSchema​

completePasswordResetSchema​

changePasswordSchema​

deactivateSchema​

activateSchema​

refreshTokenCookieSchema​

refreshTokenBearerSchema​

refreshTokenSchema​

logoutCookieSchema​

logoutBearerSchema​

deleteRefreshTokensSchema​

Inventory

Details

`passwordSchema`

`providerSchema`

`credentialsSchema`

`identitySchema`

`loginWithCredentialsSchema`

`resendMfaCodeSchema`

`verifyMfaCodeSchema`

`loginWithOnetimeTokenSchema`

`registerCredentialsSchema`

`sendVerificationEmailSchema`

`confirmEmailSchema`

`changeEmailSchema`

`checkTokenSchema`

`confirmNewEmailSchema`

`sendResetPasswordLinkEmailSchema`

`completePasswordResetSchema`

`changePasswordSchema`

`deactivateSchema`

`activateSchema`

`refreshTokenCookieSchema`

`refreshTokenBearerSchema`

`refreshTokenSchema`

`logoutCookieSchema`

`logoutBearerSchema`

`deleteRefreshTokensSchema`