API docs by Redocly

PVPipe Authentication Microservice API (1.0.0)

Download OpenAPI specification:

PVPipe Development Team: [email protected] License: Proprietary

Enterprise-grade authentication service for PVPipe document management system. Provides JWT authentication, TOTP/OTP, biometric authentication, and WebAuthn/passkeys support.

Authentication Methods

  • JWT Bearer Token: Standard authentication for API access
  • TOTP/OTP: Two-factor authentication with QR code generation
  • Biometric: Mobile device fingerprint/face authentication
  • WebAuthn/Passkeys: FIDO2 passwordless authentication

Security Features

  • Multi-token architecture (access, refresh, biometric tokens)
  • Token rotation with automatic family-based revocation
  • Device binding and trust levels
  • Comprehensive audit logging
  • Field-level encryption for sensitive data

Authentication

Core authentication endpoints for login, registration, and token management

User login

Authenticate user with email and password

Request Body schema: application/json
required

Login credentials

email
required
string
password
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "registerOtp": true,
  • "token": "string"
}

Get current user profile

Get complete user profile with short signature for file access

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "department": {
    },
  • "email": "string",
  • "employee": {
    },
  • "id": 0,
  • "isSuperAdmin": true,
  • "mfaEnabled": true,
  • "permissions": [
    ]
}

Refresh access token

Exchange refresh token for new access and refresh tokens

Request Body schema: application/json
required

Refresh token

refreshToken
required
string

Responses

Request samples

Content type
application/json
{
  • "refreshToken": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "accessTokenExpiresAt": "string",
  • "refreshToken": "string",
  • "refreshTokenExpiresAt": "string",
  • "signature": "string"
}

Register TOTP for two-factor authentication

Generate QR code for TOTP registration

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "qrCode": "string"
}

Verify TOTP code

Verify TOTP code and complete authentication

Authorizations:
BearerAuth
Request Body schema: application/json
required

OTP code

otp
required
string

Responses

Request samples

Content type
application/json
{
  • "otp": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "accessTokenExpiresAt": "string",
  • "refreshToken": "string",
  • "refreshTokenExpiresAt": "string",
  • "signature": "string"
}

Biometric

Mobile biometric authentication and device management

Initiate action confirmation

Request biometric confirmation for a sensitive action

Authorizations:
BearerAuth
Request Body schema: application/json
required

Action details for confirmation

object
actionType
required
string <= 100 characters

Responses

Request samples

Content type
application/json
{
  • "actionPayload": { },
  • "actionType": "string"
}

Response samples

Content type
application/json
{
  • "challenge": "string",
  • "confirmationId": "string",
  • "expiresAt": "string"
}

Reject action confirmation

Reject a pending action confirmation request

Authorizations:
BearerAuth
path Parameters
id
required
string

Confirmation ID

Request Body schema: application/json
required

Rejection reason (optional)

reason
string

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "confirmationId": "string",
  • "status": "pending",
  • "success": true
}

Get confirmation status

Check the status of a pending action confirmation

Authorizations:
BearerAuth
path Parameters
id
required
string

Confirmation ID

Responses

Response samples

Content type
application/json
{
  • "actionPayload": { },
  • "actionType": "string",
  • "confirmationId": "string",
  • "createdAt": "string",
  • "expiresAt": "string",
  • "status": "pending",
  • "updatedAt": "string"
}

Approve action with biometric

Approve a pending action using biometric authentication

Authorizations:
BearerAuth
path Parameters
id
required
string

Confirmation ID

Request Body schema: application/json
required

Biometric signature for approval

deviceId
required
string
signedChallenge
required
string

Base64 encoded signature

Responses

Request samples

Content type
application/json
{
  • "deviceId": "string",
  • "signedChallenge": "string"
}

Response samples

Content type
application/json
{
  • "confirmationId": "string",
  • "status": "pending",
  • "success": true
}

List user's registered devices

Get all biometric devices registered by the authenticated user

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update device FCM token

Update Firebase Cloud Messaging token for push notifications

Authorizations:
BearerAuth
Request Body schema: application/json
required

FCM token update request

deviceId
required
string
fcmToken
required
string <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "deviceId": "string",
  • "fcmToken": "string"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "success": true
}

Create device registration challenge

Generate a cryptographic challenge for registering a new biometric device

Authorizations:
BearerAuth
Request Body schema: application/json
required

Device registration details

deviceFingerprint
required
string
deviceName
required
string <= 255 characters
deviceType
required
string
Enum: "mobile" "desktop" "tablet"
keyAlgorithm
required
string
Enum: "ES256" "RS256" "PS256"
publicKey
required
string

Base64 encoded public key

Responses

Request samples

Content type
application/json
{
  • "deviceFingerprint": "string",
  • "deviceName": "string",
  • "deviceType": "mobile",
  • "keyAlgorithm": "ES256",
  • "publicKey": "string"
}

Response samples

Content type
application/json
{
  • "challenge": "string",
  • "deviceId": "string",
  • "expiresAt": "string",
  • "sessionId": "string"
}

Verify device registration

Complete device registration by verifying the signed challenge

Authorizations:
BearerAuth
Request Body schema: application/json
required

Signed challenge verification

sessionId
required
string
signedChallenge
required
string

Base64 encoded signature

Responses

Request samples

Content type
application/json
{
  • "sessionId": "string",
  • "signedChallenge": "string"
}

Response samples

Content type
application/json
{
  • "device": {
    },
  • "deviceId": "string",
  • "success": true
}

Delete a registered device

Remove a biometric device from the user's account

Authorizations:
BearerAuth
path Parameters
deviceId
required
string

Device ID

Responses

Response samples

Content type
application/json
{ }

Verify mobile biometric login

Authenticate user with biometric signature verification

Request Body schema: application/json
required

Signed challenge for authentication

rememberMe
boolean
sessionId
required
string
signedChallenge
required
string

Base64 encoded signature

Responses

Request samples

Content type
application/json
{
  • "rememberMe": true,
  • "sessionId": "string",
  • "signedChallenge": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "tokens": {
    }
}

Create mobile authentication challenge

Generate a challenge for mobile biometric authentication

Request Body schema: application/json
required

Device fingerprint

deviceFingerprint
required
string

Responses

Request samples

Content type
application/json
{
  • "deviceFingerprint": "string"
}

Response samples

Content type
application/json
{
  • "challenge": "string",
  • "expiresAt": "string",
  • "sessionId": "string"
}

Generate ECDSA key pair for mobile

Generate a valid ECDSA P-256 key pair for mobile devices that may have issues generating keys locally

Request Body schema: application/json
required

Key generation parameters

keyAlgorithm
required
string
Value: "ES256"
keyName
string

Optional name for the key

Responses

Request samples

Content type
application/json
{
  • "keyAlgorithm": "ES256",
  • "keyName": "string"
}

Response samples

Content type
application/json
{
  • "curve": "string",
  • "keyAlgorithm": "string",
  • "privateKey": "string",
  • "publicKey": "string"
}

Refresh biometric authentication token

Exchange biometric refresh token for new access and refresh tokens

Request Body schema: application/json
required

Refresh token request

refreshToken
required
string

Responses

Request samples

Content type
application/json
{
  • "refreshToken": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "tokens": {
    }
}

WebAuthn

FIDO2/WebAuthn passkey authentication endpoints

Check if user has passkeys

Check whether a user has registered any FIDO2/WebAuthn credentials

Request Body schema: application/json
required

User email

email
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "hasPasskeys": true
}

Begin passkey authentication

Start FIDO2/WebAuthn authentication challenge

Request Body schema: application/json
required

User email

email
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "publicKey": { },
  • "sessionId": "string"
}

Complete passkey authentication

Verify FIDO2/WebAuthn assertion and issue tokens

Request Body schema: application/json
required

WebAuthn assertion response

rememberMe
boolean
required
object

WebAuthn AuthenticatorAssertionResponse

sessionId
required
string

Responses

Request samples

Content type
application/json
{
  • "rememberMe": true,
  • "response": { },
  • "sessionId": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "tokens": {
    }
}

List user's passkeys

Get all registered FIDO2/WebAuthn credentials for the authenticated user

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "credentials": [
    ]
}

Delete a passkey

Remove a specific FIDO2/WebAuthn credential from the user's account

Authorizations:
BearerAuth
path Parameters
id
required
string

Credential ID

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "success": true
}

Get passkey prompt status

Check if user should be prompted to register a passkey

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "lastPrompted": "string",
  • "promptStatus": "string"
}

Update passkey prompt status

Update whether user should be prompted to register a passkey

Authorizations:
BearerAuth
Request Body schema: application/json
required

New prompt status

status
required
string
Enum: "pending" "accepted" "declined" "dismissed"

Responses

Request samples

Content type
application/json
{
  • "status": "pending"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "success": true
}

Begin passkey registration

Start FIDO2/WebAuthn passkey registration process

Authorizations:
BearerAuth
Request Body schema: application/json
required

Passkey name (optional)

name
required
string <= 255 characters

User-friendly name for the passkey

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "publicKey": { },
  • "sessionId": "string"
}

Complete passkey registration

Verify and store the new FIDO2/WebAuthn credential

Authorizations:
BearerAuth
Request Body schema: application/json
required

WebAuthn attestation response

required
object

WebAuthn AuthenticatorAttestationResponse

sessionId
required
string

Responses

Request samples

Content type
application/json
{
  • "response": { },
  • "sessionId": "string"
}

Response samples

Content type
application/json
{
  • "credential": {
    },
  • "credentialId": "string",
  • "success": true
}

Internal

Internal service-to-service authentication endpoints

Internal OTP verification

Service-to-service OTP verification endpoint

Request Body schema: application/json
required

OTP verification request

otp
required
string
userId
required
integer

Responses

Request samples

Content type
application/json
{
  • "otp": "string",
  • "userId": 0
}

Response samples

Content type
application/json
{
  • "userId": 0,
  • "valid": true
}

Forward authentication verification

Verify ULID signature for API gateway forward auth

query Parameters
signature
string

ULID signature

Responses

Response samples

Content type
application/json
"string"

Health

Service health monitoring endpoints

Service health check

Check the health status of the service and its dependencies

Responses

Response samples

Content type
application/json
{
  • "services": {
    },
  • "status": "string",
  • "timestamp": "string"
}

Liveness probe

Simple liveness check for Kubernetes

Responses

Readiness probe

Check if the service is ready to handle requests

Responses

OAuth2

JSON Web Key Set

Get public keys for verifying JWT signatures

Responses

Response samples

Content type
application/json
{ }

OAuth2 Server Metadata

Get OAuth2 authorization server metadata (RFC 8414)

Responses

Response samples

Content type
application/json
{ }

OAuth2 Authorization Endpoint

Initiates the OAuth2 authorization code flow. Supports PKCE for public clients

query Parameters
response_type
required
string

Response type (must be 'code')

client_id
required
string

OAuth2 client identifier

redirect_uri
required
string

Callback URL for authorization code

scope
string

Requested scopes (space-separated)

state
required
string

CSRF protection state parameter

code_challenge
string

PKCE code challenge (required for public clients)

code_challenge_method
string

PKCE method (S256 or plain)

Responses

Response samples

Content type
application/json
"string"

OAuth2 Authorization Endpoint

Initiates the OAuth2 authorization code flow. Supports PKCE for public clients

query Parameters
response_type
required
string

Response type (must be 'code')

client_id
required
string

OAuth2 client identifier

redirect_uri
required
string

Callback URL for authorization code

scope
string

Requested scopes (space-separated)

state
required
string

CSRF protection state parameter

code_challenge
string

PKCE code challenge (required for public clients)

code_challenge_method
string

PKCE method (S256 or plain)

Responses

Response samples

Content type
application/json
"string"

OAuth2 Token Introspection

Determine the active state and metadata of an OAuth2 token (RFC 7662)

Authorizations:
None
Request Body schema: application/x-www-form-urlencoded
required
token
required
string

Token to introspect

token_type_hint
string

Hint about token type (access_token or refresh_token)

Responses

Response samples

Content type
application/json
{
  • "active": true,
  • "aud": "string",
  • "client_id": "string",
  • "exp": 0,
  • "iat": 0,
  • "iss": "string",
  • "jti": "string",
  • "nbf": 0,
  • "scope": "string",
  • "sub": "string",
  • "token_type": "string",
  • "username": "string"
}

OAuth2 Token Revocation

Revoke an access or refresh token (RFC 7009)

Authorizations:
None
Request Body schema: application/x-www-form-urlencoded
required
token
required
string

Token to revoke

token_type_hint
string

Hint about token type (access_token or refresh_token)

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_description": "string",
  • "error_uri": "string"
}

OAuth2 Token Endpoint

Exchange authorization code or refresh token for access tokens

Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string

Grant type (authorization_code, refresh_token, client_credentials)

code
string

Authorization code (for authorization_code grant)

redirect_uri
string

Redirect URI (must match authorization request)

client_id
required
string

OAuth2 client identifier

client_secret
string

Client secret (required for confidential clients)

refresh_token
string

Refresh token (for refresh_token grant)

code_verifier
string

PKCE code verifier

scope
string

Requested scopes (for client_credentials grant)

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "expires_in": 0,
  • "id_token": "string",
  • "refresh_token": "string",
  • "scope": "string",
  • "token_type": "string"
}

Get User Information

Retrieve user profile information (OpenID Connect)

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{ }

Get User Information

Retrieve user profile information (OpenID Connect)

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{ }