📐 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}],
});

---