API v1.0

All Systems Operational

MID API Documentation

Build secure passwordless authentication and identity verification into your applications with our RESTful API. FIDO2 certified, enterprise-ready.

Quick Start

Try Sandbox

View SDK

99.99%

Uptime SLA

<100ms

Avg Response

FIDO2

Certified

18M+

API Calls/Day

Base URL & Authentication

Base URL
https://api.mobid.io/v1 

Sandbox URL
https://sandbox.mobid.io/v1 

All API requests require authentication via API key in the header:


Authorization: Bearer your_api_key_here
X-Client-ID: your_client_id

Quick Start Guide

Get started in 3 steps

Get API Keys

Create a client account and receive your clientId and apiKey

Create Consent

Initialize an authentication session and generate a QR code for your user

Verify Response

Poll for status or receive webhook callback when user completes authentication

API Reference

Consents

Create and manage authentication sessions

POST /consents/authGET /consents/:idGET /consents/qr/:type/:id

FIDO/WebAuthn

Passwordless biometric authentication

POST /fido/register/beginPOST /fido/register/completePOST /fido/authenticate/begin

Enrollments

User registration and onboarding

POST /enrollmentsPOST /enrollments/:id/verifyGET /enrollments/:id

Devices

Device registration and management

POST /devicesGET /devices/:idDELETE /devices/:id

Clients

Partner account management

POST /clientsGET /clients/:idPUT /clients/:id

Webhooks

Event notifications

POST /webhooks/stripePOST /webhooks/appstorePOST /webhooks/playstore

Interactive API Sandbox

ℹ️

Sandbox Environment

Test API endpoints with mock data. No real transactions are processed in sandbox mode.

POST/v1/consents/auth

Request Body

{
"clientId": "mid_client_xxxxxxxxxxxx",
"recipient": "+2348012345678",
"intent": "login",
"callbackUrl": "https://yourapp.com/auth/callback",
"metadata": {
  "userId": "user_123",
  "sessionId": "sess_abc"
}
}

200 OK

{
"error": false,
"code": 200,
"message": "Consent session created",
"data": {
  "sessionId": "cons_xxxxxxxxxxxxxxxx",
  "status": "pending",
  "qrCode": "https://api.mobid.io/v1/consents/qr/auth/cons_xxx",
  "deepLink": "mobid://auth?session=cons_xxx",
  "expiresAt": "2025-12-18T15:30:00Z"
}
}

FIDO2 Registration Flow

POST/v1/fido/register/begin

Request Body

{
"mobile": "+2348012345678",
"deviceId": "device_xxxxxxxx",
"deviceInfo": {
  "model": "iPhone 15 Pro",
  "os": "iOS 17.2",
  "appVersion": "2.1.0"
}
}

200 OK - Registration Options

{
"error": false,
"code": 200,
"message": "Registration options generated",
"data": {
  "challenge": "base64-encoded-challenge",
  "rp": {
    "name": "MID - Mobile Identity",
    "id": "mobid.io"
  },
  "user": {
    "id": "base64-user-id",
    "name": "+2348012345678",
    "displayName": "User"
  },
  "pubKeyCredParams": [
    { "type": "public-key", "alg": -7 },
    { "type": "public-key", "alg": -257 }
  ],
  "authenticatorSelection": {
    "authenticatorAttachment": "platform",
    "userVerification": "required"
  }
}
}

SDK Code Examples

Webhook Events

Configure webhooks to receive real-time notifications when authentication events occur.

Available Events

consent.created— New consent session created

consent.approved— User approved the consent

consent.rejected— User rejected the consent

consent.expired— Consent session timed out

device.registered— New device registered

device.deregistered— Device removed

Webhook Payload Example


{
  "event": "consent.approved",
  "timestamp": "2025-12-18T14:30:00Z",
  "data": {
    "sessionId": "cons_xxxxxxxxxxxxxxxx",
    "clientId": "mid_client_xxxx",
    "recipient": "+2348012345678",
    "intent": "login",
    "status": "approved",
    "user": {
      "id": "user_xxxxxxxx",
      "mobile": "+2348012345678",
      "verified": true
    },
    "device": {
      "id": "device_xxxxxxxx",
      "model": "iPhone 15 Pro"
    }
  },
  "signature": "sha256=xxxxxxxxxxxxxxxxxxxxxxxx"
}

Rate Limits

Endpoint	Limit	Window
`/v1/consents/*`	1,000 requests	1 minute
`/v1/auth/*`	1,000 requests	15 minutes
`/v1/fido/*`	20 requests	15 minutes
`/v1/enrollments`	5 requests	1 hour (per device)
`/v1/devices`	30 requests	15 minutes

Error Handling

Error Response Format

{
"error": true,
"code": 429,
"message": "Too many enrollment attempts from this device",
"retryAfter": 3600,
"resetTime": "2025-12-18T15:30:00Z",
"limit": 5,
"remaining": 0
}

Code	Description
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn’t exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Security Best Practices

Use HTTPS Only

All API requests must use HTTPS encryption

Secure API Keys

Never expose keys in client-side code or version control

Validate Webhooks

Always verify webhook signatures before processing

Implement Retries

Use exponential backoff for failed requests

Need Help?

Full API Reference

Detailed documentation for all endpoints

SDK & Examples

Official SDKs and code samples

Developer Support

Get help from our engineering team

MID API Documentation

Base URL & Authentication

Quick Start Guide

Get started in 3 steps

Get API Keys

Create Consent

Verify Response

API Reference

Consents

FIDO/WebAuthn

Enrollments

Devices

Clients

Webhooks

Interactive API Sandbox

Create Authentication Consent

FIDO2 Registration Flow

SDK Code Examples

Webhook Events

Available Events

Webhook Payload Example

Rate Limits

Error Handling

Security Best Practices

Use HTTPS Only

Secure API Keys

Validate Webhooks

Implement Retries

Need Help?

Full API Reference

SDK & Examples

Developer Support