Devices API

This is the Devices API that provides programmatic access to various resources and services. The API supports the following areas: Device PIN Protection, Device Activation, Device Enrollment, Device Management. All endpoints require authentication using a Bearer token.

The devices model

The devices model contains all the information about your devices entities.

Properties

Name
deviceId
Type
string
Description
Value for deviceId
Name
status
Type
string
Description
Current status or state of status
Name
enrollmentStatus
Type
string
Description
Value for enrollmentStatus
Name
certificateStatus
Type
string
Description
Value for certificateStatus
Name
lastActivity
Type
string
Description
Value for lastActivity
Name
deviceInfo
Type
object
Description
Object containing deviceInfo data
Name
securityPosture
Type
object
Description
Object containing securityPosture data

Check Device Status

Retrieves current device status and activation state for security monitoring and compliance purposes

Request

GET

/v1/device/status

curl -G https://api.adiba.app/v1/device/status \
  -H "Authorization: Bearer {token}"

{
"deviceId": "DEV_001_20241201_001",
"status": "ACTIVE",
"enrollmentStatus": "ENROLLED",
"certificateStatus": "VALID",
"lastActivity": "2024-12-01T14:30:00Z",
"deviceInfo": {
    "type": "MOBILE",
    "manufacturer": "Apple",
    "model": "iPhone 15",
    "osVersion": "iOS 17.1",
    "appVersion": "2.1.0"
},
"securityPosture": {
    "pinEnabled": true,
    "certificateValid": true,
    "lastSecurityCheck": "2024-12-01T14:25:00Z"
}
}

(de)Activate Device

Enables or disables device access to banking services with immediate security enforcement

Request

POST

/v1/device/status

curl -X POST https://api.adiba.app/v1/device/status \
  -H "Authorization: Bearer {token}" \
  -d '{
"deviceId": "DEV_001_20241201_001",
"action": "ACTIVATE",
"reason": "New device enrollment approved",
"adminId": "ADMIN_001"
}'

{
"status": "SUCCESS",
"deviceId": "DEV_001_20241201_001",
"newState": "ACTIVE",
"updatedAt": "2024-12-01T14:35:00Z",
"message": "Device activated successfully",
"sessionsTerminated": 0
}

Request CSR for Device

Generates Certificate Signing Request for device enrollment and secure communication setup

Request

POST

/v1/device/cert/request

curl -X POST https://api.adiba.app/v1/device/cert/request \
  -H "Authorization: Bearer {token}" \
  -d '{
"deviceId": "DEV_001_20241201_001",
"keyAlgorithm": "RSA",
"keySize": 2048,
"subjectDN": {
    "CN": "DEV_001_20241201_001",
    "O": "Digital Bank Ltd",
    "OU": "IT Department",
    "C": "NG"
},
"san": [
    "device.digitalbank.com",
    "DEV_001_20241201_001.internal"
]
}'

{
"csrId": "CSR_001_20241201_001",
"status": "PENDING",
"csrContent": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0...",
"requestedAt": "2024-12-01T14:40:00Z",
"estimatedProcessingTime": "5-10 minutes",
"message": "CSR generated successfully and submitted for signing"
}

Sign CSR for Device

Processes and signs Certificate Signing Request to issue valid device certificates

Request

POST

/v1/device/cert/sign

curl -X POST https://api.adiba.app/v1/device/cert/sign \
  -H "Authorization: Bearer {token}" \
  -d '{
"csrId": "CSR_001_20241201_001",
"validityDays": 365,
"certificateExtensions": {
    "keyUsage": [
        "DIGITAL_SIGNATURE",
        "KEY_ENCIPHERMENT",
        "DATA_ENCIPHERMENT"
    ],
    "extendedKeyUsage": [
        "CLIENT_AUTH",
        "SERVER_AUTH"
    ],
    "subjectAltName": [
        "DNS:device.digitalbank.com",
        "DNS:DEV_001_20241201_001.internal"
    ]
}
}'

{
"certificateId": "CERT_001_20241201_001",
"status": "SIGNED",
"certificateContent": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...",
"validFrom": "2024-12-01T14:45:00Z",
"validTo": "2025-12-01T14:45:00Z",
"serialNumber": "01:02:03:04:05:06:07:08:09:0A",
"message": "Certificate signed successfully"
}

Rotate Expiring Certificates

Automatically renews device certificates before expiration to maintain continuous security

Request

POST

/v1/device/cert/rotate

curl -X POST https://api.adiba.app/v1/device/cert/rotate \
  -H "Authorization: Bearer {token}" \
  -d '{
"deviceId": "DEV_001_20241201_001",
"rotationType": "AUTOMATIC",
"forceRotation": false
}'

{
"rotationId": "ROT_001_20241201_001",
"status": "IN_PROGRESS",
"oldCertificateId": "CERT_001_20241201_001",
"newCertificateId": "CERT_002_20241201_001",
"estimatedCompletion": "2024-12-01T15:00:00Z",
"message": "Certificate rotation initiated successfully"
}

Transfer Device Ownership

Initiates secure device ownership transfer between authorized users with validation

Request

POST

/v1/device/ownership/transfer

curl -X POST https://api.adiba.app/v1/device/ownership/transfer \
  -H "Authorization: Bearer {token}" \
  -d '{
"deviceId": "DEV_001_20241201_001",
"currentOwnerId": "USR_001_20241201_001",
"newOwnerId": "USR_002_20241201_001",
"transferReason": "Employee transfer to new department",
"effectiveDate": "2024-12-02T00:00:00Z"
}'

{
"transferId": "TRF_001_20241201_001",
"status": "PENDING_APPROVAL",
"deviceId": "DEV_001_20241201_001",
"currentOwnerId": "USR_001_20241201_001",
"newOwnerId": "USR_002_20241201_001",
"requestedAt": "2024-12-01T14:50:00Z",
"message": "Ownership transfer request submitted successfully"
}

Accept Transfer Request

Processes and completes device ownership transfer upon recipient acceptance

Request

POST

/v1/device/ownership/accept

curl -X POST https://api.adiba.app/v1/device/ownership/accept \
  -H "Authorization: Bearer {token}" \
  -d '{
"transferId": "TRF_001_20241201_001",
"acceptorId": "USR_002_20241201_001",
"acceptanceCode": "123456"
}'

{
"status": "SUCCESS",
"transferId": "TRF_001_20241201_001",
"deviceId": "DEV_001_20241201_001",
"newOwnerId": "USR_002_20241201_001",
"completedAt": "2024-12-01T15:00:00Z",
"message": "Device ownership transfer completed successfully"
}

Create Device PIN

Establishes secure PIN protection for device access with encryption and validation

Request

POST

/v1/device/pin

curl -X POST https://api.adiba.app/v1/device/pin \
  -H "Authorization: Bearer {token}" \
  -d '{
"deviceId": "DEV_001_20241201_001",
"pin": "123456",
"confirmPin": "123456",
"userId": "USR_001_20241201_001"
}'

{
"status": "SUCCESS",
"deviceId": "DEV_001_20241201_001",
"pinCreatedAt": "2024-12-01T15:05:00Z",
"message": "Device PIN created successfully",
"nextSteps": [
    "Test PIN authentication",
    "Enable biometric authentication if available"
]
}

Change Device PIN

Updates existing device PIN with current PIN verification and security validation

Request

POST

/v1/device/pin/change

curl -X POST https://api.adiba.app/v1/device/pin/change \
  -H "Authorization: Bearer {token}" \
  -d '{
"deviceId": "DEV_001_20241201_001",
"currentPin": "123456",
"newPin": "654321",
"confirmNewPin": "654321",
"userId": "USR_001_20241201_001"
}'

{
"status": "SUCCESS",
"deviceId": "DEV_001_20241201_001",
"pinChangedAt": "2024-12-01T15:10:00Z",
"message": "Device PIN changed successfully",
"sessionsInvalidated": 2
}

Reset Device PIN

Initiates PIN reset process with secure verification and temporary access

Request

POST

/v1/device/pin/reset

curl -X POST https://api.adiba.app/v1/device/pin/reset \
  -H "Authorization: Bearer {token}" \
  -d '{
"deviceId": "DEV_001_20241201_001",
"userId": "USR_001_20241201_001",
"resetMethod": "SMS",
"verificationData": {
    "phoneNumber": "+2348012345678",
    "email": "john.doe@email.com"
}
}'

{
"resetId": "RESET_001_20241201_001",
"status": "PENDING",
"resetMethod": "SMS",
"expiresAt": "2024-12-01T16:05:00Z",
"message": "PIN reset initiated successfully",
"nextStep": "Enter the verification code sent to your phone"
}

Confirm PIN Reset

Validates reset token and allows user to set new PIN with security checks

Request

POST

/v1/device/pin/confirm

curl -X POST https://api.adiba.app/v1/device/pin/confirm \
  -H "Authorization: Bearer {token}" \
  -d '{
"resetId": "RESET_001_20241201_001",
"verificationCode": "123456",
"newPin": "789012",
"confirmNewPin": "789012"
}'

{
"status": "SUCCESS",
"deviceId": "DEV_001_20241201_001",
"pinResetAt": "2024-12-01T15:15:00Z",
"message": "PIN reset completed successfully",
"temporaryAccessRevoked": true
}