Skip to content
DEVELOPER DOCUMENTATION
/
API Overview
/
/
Check holder data

Lean Disposable Services (26.1.0.3)

REST API for enrolling and managing lean disposable certificates for secure digital signatures.

Authenticate every request with Basic Auth credentials and a client SSL certificate (mTLS). All requests require the Content-Type: application/json header.

For the full integration guide, see the Lean Disposable documentation.

Lean Disposable documentation
Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Production environment
https://lean.namirialtsp.com/RAWS_DISPOSABLE
Development and testing environment
https://lean.test.namirialtsp.com/RAWS_DISPOSABLE

Certificate

Methods to validate holder data, enroll disposable certificates, and send OTP codes.

Operations

Send OTP

Request

Sends an OTP code to the holder via SMS or email. Use certIdOtp and deviceCode returned by enroll. See sendOtp.

Security
basicAuth and sslCertificate
Bodyapplication/json
certIdOtpinteger(int32)required

OTP certificate identifier returned by enroll (certIdOtp).

Example: 1234567
deviceCodestringrequired

Device code returned by enroll (deviceCode).

Example: "RHIDP0000000000000"
smsOptionsobject(SmsOptions)

Required if otpType=SMS.

emailOptionsobject(EmailOptions)

Required if otpType=EMAIL.

curl -i -X POST \
  -u <username>:<password> \
  https://lean.namirialtsp.com/RAWS_DISPOSABLE/api/certificate/sendOtp \
  -H 'Content-Type: application/json' \
  -d '{
    "certIdOtp": 1234567,
    "deviceCode": "RHIDP0000000000000",
    "smsOptions": {
      "textSMS": "Your OTP code is: $OTP$"
    }
  }'

Responses

OTP sent successfully. Response body is empty.

Response
No content

Validate certificate data

Request

Validates the OTP code entered by the holder. See validate.

Security
basicAuth and sslCertificate
Bodyapplication/json
certIdOtpinteger(int32)required

OTP certificate identifier returned by enroll (certIdOtp).

Example: 1234567
deviceCodestringrequired

Device code returned by enroll (deviceCode).

Example: "RHIDP0000000000000"
otpCodestringrequired

OTP code entered by the user.

Example: "123456"
curl -i -X POST \
  -u <username>:<password> \
  https://lean.namirialtsp.com/RAWS_DISPOSABLE/api/certificate/validate \
  -H 'Content-Type: application/json' \
  -d '{
    "certIdOtp": 1234567,
    "deviceCode": "RHIDP0000000000000",
    "otpCode": "123456"
  }'

Responses

OK

Response
No content

Check holder data

Request

Validates holder data, document and certificate parameters before enrolling. Optional step — use it to detect validation errors before calling enroll. See checkData.

Security
basicAuth and sslCertificate
Path
lraIdstringrequired

Local Registration Authority (LRA) identifier.

Bodyapplication/json
disposableHolderobject(DisposableHolder)required
disposableHolder.​firstNamestring<= 64 charactersrequired

First name of the holder (UTF-8). See allowed characters rules.

disposableHolder.​lastNamestring<= 64 charactersrequired

Last name of the holder (UTF-8). See allowed characters rules.

disposableHolder.​identificationTypestring(DisposableHolderIdentificationType)required

Type of identification document. Together with identificationCode and identificationCountry it composes the certificate serial number.

Enum"ITALIAN_TAX_CODE""FOREIGN_TAX_CODE""PASSPORT""PERSONAL_NUMBER""NATIONAL_IDENTITY_CARD""DRIVING_LICENSE""RESIDENCE_PERMIT""RESIDENCE_PERMIT_TEMP""EMBASSY_DOCUMENT""AM"
disposableHolder.​identificationCodestringrequired

Unique code of the identification document. Together with identificationType and identificationCountry it composes the certificate serial number. See allowed characters rules.

disposableHolder.​identificationCountrystring^[A-Z]{2}$required

Country where identification was issued. ISO 3166-1 alpha-2 code.

disposableHolder.​birthDatestring(date)^\d{4}-\d{2}-\d{2}$

Date of birth in ISO 8601 format (yyyy-MM-dd). Example: 1980-01-01. Note: the date is not validated semantically by the backend.

Example: "1980-01-01"
disposableHolder.​birthCitystring

City of birth. See allowed characters rules.

disposableHolder.​citizenShipstring^[A-Z]{2}$

Citizenship country. ISO 3166-1 alpha-2 code.

disposableContactsobject(DisposableContacts)

Required if otpType=SMS (provide mobile) or otpType=EMAIL (provide email).

disposableDocobject(DisposableDoc)required

Identity document information.

Not required if one of the following conditions is true:

  • DisposableIdentification.identificationType is AML
  • DisposableHolder.identificationType is one of: PASSPORT, PERSONAL_NUMBER, NATIONAL_IDENTITY_CARD, DRIVING_LICENSE, RESIDENCE_PERMIT, RESIDENCE_PERMIT_TEMP, EMBASSY_DOCUMENT
disposableDoc.​documentTypestringrequired

Identity document type. See allowed values.

Enum"CI""PASS""PA""RP""CIE""RT""DC""AT"
disposableDoc.​documentNrstringrequired

Document number.

disposableDoc.​documentIssuerstring

Entity that issued the document.

disposableDoc.​documentIssuerDatestring(date)^\d{4}-\d{2}-\d{2}$required

Date on which the document was issued. ISO 8601 format yyyy-MM-dd. Other formats are not accepted.

disposableDoc.​documentIssuerCountrystring^[A-Z]{2}$required

Country where document was issued. ISO 3166-1 alpha-2 code.

disposableDoc.​documentExpirationDatestring(date)^\d{4}-\d{2}-\d{2}$required

Date on which the document was expires. ISO 8601 format yyyy-MM-dd. Other formats are not accepted.

disposableCertificateobject(DisposableCertificate)required
disposableCertificate.​passwordstring[ 8 .. 32 ] characters^[A-Za-z0-9]+$required

Certificate PIN.

disposableCertificate.​securityCodestring[ 8 .. 32 ] characters^[A-Za-z0-9]+$required

Certificate security code.

disposableCertificate.​fullDataboolean

Enroll with full profile. Default: false.

disposableCertificate.​withoutUsageLimitLRAboolean

Omit LRA limitation of use (LoU). Default: false.

disposableCertificate.​typestring(DisposableType)

Disposable certificate type. See allowed values. Default: DISPOSABLE.

Enum"DISPOSABLE""DISPOSABLE_30_DAYS""LONG_LIVED""DISPOSABLE_FEA"
disposableCertificate.​otpTypestring(DisposableOtpType)

OTP delivery method. See allowed values. Default: SMS.

Enum"SMS""EMAIL""NO_OTP""EXTERNAL_OTP"
disposableCertificate.​transactionLimitobject(TransactionLimit)
disposableCertificate.​limitationOfUseobject(LimitationOfUse)
identificationobject(DisposableIdentification)
disposableAddressobject(DisposableAddress)
buReIdstring<= 255 characters

Business Relation Identifier for One Platform integration.

curl -i -X POST \
  -u <username>:<password> \
  'https://lean.namirialtsp.com/RAWS_DISPOSABLE/api/certificate/{lraId}/checkData' \
  -H 'Content-Type: application/json' \
  -d '{
    "disposableHolder": {
      "firstName": "Mario",
      "lastName": "Rossi",
      "identificationType": "ITALIAN_TAX_CODE",
      "identificationCode": "RSSMRA80A01H501U",
      "identificationCountry": "IT",
      "birthDate": "1980-01-01",
      "birthCity": "Roma"
    },
    "disposableDoc": {
      "documentType": "CI",
      "documentNr": "AA0000000",
      "documentIssuer": "Comune di Roma",
      "documentIssuerDate": "2020-01-01",
      "documentIssuerCountry": "IT",
      "documentExpirationDate": "2030-01-01"
    },
    "disposableCertificate": {
      "password": "Password01",
      "securityCode": "Security01",
      "type": "DISPOSABLE",
      "otpType": "SMS"
    },
    "disposableContacts": {
      "mobile": "+390000000000"
    }
  }'

Responses

OK

Response
No content

Check holder data with eID assertion

Request

Validates holder data using an eID assertion before enrolling. Checks: mandatory fields, allowed values, LRA authorization for the eID type. See checkDataWitheIDAssertion and How to enroll with eID assertion.

Security
basicAuth and sslCertificate
Path
lraIdstringrequired

Local Registration Authority (LRA) identifier.

Bodyapplication/jsonrequired
eidAssertionHolderobject(DisposableeIDAssertionHolder)required

eID assertion holder data. The country and eIDType together identify the eID method (e.g., IT-SPID, IT-EIDNAMIRIAL, AT-EID). The assertion format depends on the eID type.

eidAssertionHolder.​countrystring^[A-Z]{2}$required

Country code of the eID provider. ISO 3166-1 alpha-2 code. Together with eIDType identifies the eID method (e.g., IT-SPID, IT-EIDNAMIRIAL, AT-EID).

Example: "IT"
eidAssertionHolder.​eIDTypestringrequired

Type of eID assertion. Together with country identifies the eID method (e.g., IT-SPID, IT-EIDNAMIRIAL, AT-EID). Allowed values depend on LRA configuration.

Example: "SPID"
eidAssertionHolder.​assertionstring(binary)required

Base64-encoded eID assertion. The format depends on eIDType.

certificateobject(DisposableCertificate)required

Certificate configuration. Specifies password, security code, certificate type, and OTP type.

certificate.​passwordstring[ 8 .. 32 ] characters^[A-Za-z0-9]+$required

Certificate PIN.

certificate.​securityCodestring[ 8 .. 32 ] characters^[A-Za-z0-9]+$required

Certificate security code.

certificate.​fullDataboolean

Enroll with full profile. Default: false.

certificate.​withoutUsageLimitLRAboolean

Omit LRA limitation of use (LoU). Default: false.

certificate.​typestring(DisposableType)

Disposable certificate type. See allowed values. Default: DISPOSABLE.

Enum"DISPOSABLE""DISPOSABLE_30_DAYS""LONG_LIVED""DISPOSABLE_FEA"
certificate.​otpTypestring(DisposableOtpType)

OTP delivery method. See allowed values. Default: SMS.

Enum"SMS""EMAIL""NO_OTP""EXTERNAL_OTP"
certificate.​transactionLimitobject(TransactionLimit)
certificate.​limitationOfUseobject(LimitationOfUse)
contactsobject(DisposableContacts)

Contact information. Required if certificate.otpType=SMS (provide mobile) or certificate.otpType=EMAIL (provide email).

buReIdstring

Business relation identifier (optional).

curl -i -X POST \
  -u <username>:<password> \
  'https://lean.namirialtsp.com/RAWS_DISPOSABLE/api/certificate/{lraId}/checkDataWitheIDAssertion' \
  -H 'Content-Type: application/json' \
  -d '{
    "eidAssertionHolder": {
      "country": "IT",
      "eIDType": "EIDNAMIRIAL",
      "assertion": "eyJnaXZlbl9uYW1lIjoiTWFyaW8iLCJmYW1pbHlfbmFtZSI6IlJvc3NpIiwicGVyc29uX2lkZW50aWZpZXIiOiJUSU5JVC1SU1NNUkE4MEEwMUg1MDFVIiwiYmlydGhfZGF0ZSI6IjE5ODAtMDEtMDEiLCJkb2NfdHlwZSI6Ik5BVElPTkFMX0lERU5USVRZX0NBUkQiLCJjb3VudHJ5IjoiSVQiLCJycF9uYW1lIjoiTmFtaXJpYWwgVGVzdCBSUCIsInJwX2lkIjoidGVzdC1ycC0wMDEiLCJvcmlnaW5hbF9hc3NlcnRpb24iOiJiYXNlNjRfZW5jb2RlZF9zYW1sX2Fzc2VydGlvbl9oZXJlIiwiaWF0IjoxNzA5NTY4MDAwfQ=="
    },
    "contacts": {
      "mobile": "+390000000000"
    },
    "certificate": {
      "fullData": false,
      "otpType": "SMS",
      "password": "Password01",
      "securityCode": "Security01",
      "type": "DISPOSABLE"
    }
  }'

Responses

Validation successful. The holder data is valid and the LRA is authorized for the specified eID type. Response body is empty.

Response
No content

Enroll disposable certificate

Request

Enrolls a disposable certificate for the holder. Returns certIdOtp and deviceCode required by sendOtp and validate. See enroll.

Security
basicAuth and sslCertificate
Path
lraIdstringrequired

Local Registration Authority (LRA) identifier.

Bodyapplication/json
disposableHolderobject(DisposableHolder)required
disposableHolder.​firstNamestring<= 64 charactersrequired

First name of the holder (UTF-8). See allowed characters rules.

disposableHolder.​lastNamestring<= 64 charactersrequired

Last name of the holder (UTF-8). See allowed characters rules.

disposableHolder.​identificationTypestring(DisposableHolderIdentificationType)required

Type of identification document. Together with identificationCode and identificationCountry it composes the certificate serial number.

Enum"ITALIAN_TAX_CODE""FOREIGN_TAX_CODE""PASSPORT""PERSONAL_NUMBER""NATIONAL_IDENTITY_CARD""DRIVING_LICENSE""RESIDENCE_PERMIT""RESIDENCE_PERMIT_TEMP""EMBASSY_DOCUMENT""AM"
disposableHolder.​identificationCodestringrequired

Unique code of the identification document. Together with identificationType and identificationCountry it composes the certificate serial number. See allowed characters rules.

disposableHolder.​identificationCountrystring^[A-Z]{2}$required

Country where identification was issued. ISO 3166-1 alpha-2 code.

disposableHolder.​birthDatestring(date)^\d{4}-\d{2}-\d{2}$

Date of birth in ISO 8601 format (yyyy-MM-dd). Example: 1980-01-01. Note: the date is not validated semantically by the backend.

Example: "1980-01-01"
disposableHolder.​birthCitystring

City of birth. See allowed characters rules.

disposableHolder.​citizenShipstring^[A-Z]{2}$

Citizenship country. ISO 3166-1 alpha-2 code.

disposableContactsobject(DisposableContacts)

Required if otpType=SMS (provide mobile) or otpType=EMAIL (provide email).

disposableDocobject(DisposableDoc)required

Identity document information.

Not required if one of the following conditions is true:

  • DisposableIdentification.identificationType is AML
  • DisposableHolder.identificationType is one of: PASSPORT, PERSONAL_NUMBER, NATIONAL_IDENTITY_CARD, DRIVING_LICENSE, RESIDENCE_PERMIT, RESIDENCE_PERMIT_TEMP, EMBASSY_DOCUMENT
disposableDoc.​documentTypestringrequired

Identity document type. See allowed values.

Enum"CI""PASS""PA""RP""CIE""RT""DC""AT"
disposableDoc.​documentNrstringrequired

Document number.

disposableDoc.​documentIssuerstring

Entity that issued the document.

disposableDoc.​documentIssuerDatestring(date)^\d{4}-\d{2}-\d{2}$required

Date on which the document was issued. ISO 8601 format yyyy-MM-dd. Other formats are not accepted.

disposableDoc.​documentIssuerCountrystring^[A-Z]{2}$required

Country where document was issued. ISO 3166-1 alpha-2 code.

disposableDoc.​documentExpirationDatestring(date)^\d{4}-\d{2}-\d{2}$required

Date on which the document was expires. ISO 8601 format yyyy-MM-dd. Other formats are not accepted.

disposableCertificateobject(DisposableCertificate)required
disposableCertificate.​passwordstring[ 8 .. 32 ] characters^[A-Za-z0-9]+$required

Certificate PIN.

disposableCertificate.​securityCodestring[ 8 .. 32 ] characters^[A-Za-z0-9]+$required

Certificate security code.

disposableCertificate.​fullDataboolean

Enroll with full profile. Default: false.

disposableCertificate.​withoutUsageLimitLRAboolean

Omit LRA limitation of use (LoU). Default: false.

disposableCertificate.​typestring(DisposableType)

Disposable certificate type. See allowed values. Default: DISPOSABLE.

Enum"DISPOSABLE""DISPOSABLE_30_DAYS""LONG_LIVED""DISPOSABLE_FEA"
disposableCertificate.​otpTypestring(DisposableOtpType)

OTP delivery method. See allowed values. Default: SMS.

Enum"SMS""EMAIL""NO_OTP""EXTERNAL_OTP"
disposableCertificate.​transactionLimitobject(TransactionLimit)
disposableCertificate.​limitationOfUseobject(LimitationOfUse)
identificationobject(DisposableIdentification)
disposableAddressobject(DisposableAddress)
buReIdstring<= 255 characters

Business Relation Identifier for One Platform integration.

curl -i -X POST \
  -u <username>:<password> \
  'https://lean.namirialtsp.com/RAWS_DISPOSABLE/api/certificate/{lraId}/enroll' \
  -H 'Content-Type: application/json' \
  -d '{
    "disposableHolder": {
      "firstName": "Mario",
      "lastName": "Rossi",
      "identificationType": "ITALIAN_TAX_CODE",
      "identificationCode": "RSSMRA80A01H501U",
      "identificationCountry": "IT",
      "birthDate": "1980-01-01",
      "birthCity": "Roma"
    },
    "disposableDoc": {
      "documentType": "CI",
      "documentNr": "AA0000000",
      "documentIssuer": "Comune di Roma",
      "documentIssuerDate": "2020-01-01",
      "documentIssuerCountry": "IT",
      "documentExpirationDate": "2030-01-01"
    },
    "disposableCertificate": {
      "password": "Password01",
      "securityCode": "Security01",
      "type": "DISPOSABLE",
      "otpType": "SMS"
    },
    "disposableContacts": {
      "mobile": "+390000000000"
    }
  }'

Responses

Issued disposable certificate. See DisposableIssued.

Bodyapplication/json
certstring(binary)

Base64-encoded DER certificate.

certTypestring(DisposableType)

Certificate type, as specified in disposableCertificate.type.

Enum"DISPOSABLE""DISPOSABLE_30_DAYS""LONG_LIVED""DISPOSABLE_FEA"
certUsageLimitstring

Limitation of use (LoU) text embedded in the certificate.

certSerialNumberstring

Certificate serial number (hex).

Example: "60F2373BFCEB569E"
certIdOtpinteger or null(int32)

OTP certificate identifier. Pass this value to sendOtp and validate. null if otpType=NO_OTP or otpType=EXTERNAL_OTP.

Example: 1234567
deviceCodestring

Device code associated with the issued certificate. Pass this value to sendOtp and validate.

Example: "RHIDP0000000000000"
Response
application/json
{
  "cert": "string",
  "certType": "DISPOSABLE",
  "certUsageLimit": "string",
  "certSerialNumber": "60F2373BFCEB569E",
  "certIdOtp": 1234567,
  "deviceCode": "RHIDP0000000000000"
}

Enroll disposable certificate with eID assertion

Request

Enrolls a disposable certificate using an eID assertion. Returns certificate details and OTP identifier (if otpType=SMS or otpType=EMAIL). See enrollDisposableWitheIDAssertion and How to enroll with eID assertion.

Security
basicAuth and sslCertificate
Path
lraIdstringrequired

Local Registration Authority (LRA) identifier.

Bodyapplication/jsonrequired
eidAssertionHolderobject(DisposableeIDAssertionHolder)required

eID assertion holder data. The country and eIDType together identify the eID method (e.g., IT-SPID, IT-EIDNAMIRIAL, AT-EID). The assertion format depends on the eID type.

eidAssertionHolder.​countrystring^[A-Z]{2}$required

Country code of the eID provider. ISO 3166-1 alpha-2 code. Together with eIDType identifies the eID method (e.g., IT-SPID, IT-EIDNAMIRIAL, AT-EID).

Example: "IT"
eidAssertionHolder.​eIDTypestringrequired

Type of eID assertion. Together with country identifies the eID method (e.g., IT-SPID, IT-EIDNAMIRIAL, AT-EID). Allowed values depend on LRA configuration.

Example: "SPID"
eidAssertionHolder.​assertionstring(binary)required

Base64-encoded eID assertion. The format depends on eIDType.

certificateobject(DisposableCertificate)required

Certificate configuration. Specifies password, security code, certificate type, and OTP type.

certificate.​passwordstring[ 8 .. 32 ] characters^[A-Za-z0-9]+$required

Certificate PIN.

certificate.​securityCodestring[ 8 .. 32 ] characters^[A-Za-z0-9]+$required

Certificate security code.

certificate.​fullDataboolean

Enroll with full profile. Default: false.

certificate.​withoutUsageLimitLRAboolean

Omit LRA limitation of use (LoU). Default: false.

certificate.​typestring(DisposableType)

Disposable certificate type. See allowed values. Default: DISPOSABLE.

Enum"DISPOSABLE""DISPOSABLE_30_DAYS""LONG_LIVED""DISPOSABLE_FEA"
certificate.​otpTypestring(DisposableOtpType)

OTP delivery method. See allowed values. Default: SMS.

Enum"SMS""EMAIL""NO_OTP""EXTERNAL_OTP"
certificate.​transactionLimitobject(TransactionLimit)
certificate.​limitationOfUseobject(LimitationOfUse)
contactsobject(DisposableContacts)

Contact information. Required if certificate.otpType=SMS (provide mobile) or certificate.otpType=EMAIL (provide email).

buReIdstring

Business relation identifier (optional).

curl -i -X POST \
  -u <username>:<password> \
  'https://lean.namirialtsp.com/RAWS_DISPOSABLE/api/certificate/{lraId}/enrollDisposableWitheIDAssertion' \
  -H 'Content-Type: application/json' \
  -d '{
    "eidAssertionHolder": {
      "country": "IT",
      "eIDType": "EIDNAMIRIAL",
      "assertion": "eyJnaXZlbl9uYW1lIjoiTWFyaW8iLCJmYW1pbHlfbmFtZSI6IlJvc3NpIiwicGVyc29uX2lkZW50aWZpZXIiOiJUSU5JVC1SU1NNUkE4MEEwMUg1MDFVIiwiYmlydGhfZGF0ZSI6IjE5ODAtMDEtMDEiLCJkb2NfdHlwZSI6Ik5BVElPTkFMX0lERU5USVRZX0NBUkQiLCJjb3VudHJ5IjoiSVQiLCJycF9uYW1lIjoiTmFtaXJpYWwgVGVzdCBSUCIsInJwX2lkIjoidGVzdC1ycC0wMDEiLCJvcmlnaW5hbF9hc3NlcnRpb24iOiJiYXNlNjRfZW5jb2RlZF9zYW1sX2Fzc2VydGlvbl9oZXJlIiwiaWF0IjoxNzA5NTY4MDAwfQ=="
    },
    "contacts": {
      "mobile": "+390000000000"
    },
    "certificate": {
      "fullData": false,
      "otpType": "SMS",
      "password": "Password01",
      "securityCode": "Security01",
      "type": "DISPOSABLE"
    }
  }'

Responses

Disposable certificate enrolled successfully. Returns certificate details and OTP identifier (if applicable). See DisposableIssued.

Bodyapplication/json
certstring(binary)

Base64-encoded DER certificate.

certTypestring(DisposableType)

Certificate type, as specified in disposableCertificate.type.

Enum"DISPOSABLE""DISPOSABLE_30_DAYS""LONG_LIVED""DISPOSABLE_FEA"
certUsageLimitstring

Limitation of use (LoU) text embedded in the certificate.

certSerialNumberstring

Certificate serial number (hex).

Example: "60F2373BFCEB569E"
certIdOtpinteger or null(int32)

OTP certificate identifier. Pass this value to sendOtp and validate. null if otpType=NO_OTP or otpType=EXTERNAL_OTP.

Example: 1234567
deviceCodestring

Device code associated with the issued certificate. Pass this value to sendOtp and validate.

Example: "RHIDP0000000000000"
Response
application/json
{
  "cert": "string",
  "certType": "DISPOSABLE",
  "certUsageLimit": "string",
  "certSerialNumber": "60F2373BFCEB569E",
  "certIdOtp": 1234567,
  "deviceCode": "RHIDP0000000000000"
}

Document

Methods to retrieve disposable contracts and upload documents related to the issued certificate.

Operations

Utility

Methods to verify service status and retrieve error information.

Operations