API Reference

Complete reference for all MID API endpoints. All endpoints are versioned under /v1 and use JSON for request/response bodies.

ℹ️

Base URLs

Production: https://api.mobid.io/v1
Sandbox: https://sandbox.api.mobid.io/v1

Authentication

All API requests require authentication via API key or OAuth 2.0 token in the Authorization header.


# API Key authentication
Authorization: Bearer mk_live_your_api_key_here
 
# OAuth 2.0 token
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Endpoints Overview

Auth

/v1/auth/*

FIDO authentication sessions, QR validation, and credential verification.

Consents

/v1/consents/*

Create and manage user consent sessions for authentication and transactions.

FIDO

/v1/fido/*

WebAuthn/FIDO2 registration and authentication endpoints.

Devices

/v1/devices/*

Device registration, activation, and credential management.

Clients

/v1/clients/*

Partner/client management and API key operations.

Webhooks

/v1/webhooks/*

Receive real-time notifications for events.

Create a new consent session for user authentication. Returns a session ID and QR code for mobile scanning.

POST

https://sandbox.api.mobid.io/v1/consents/auth

Creates a new authentication consent session. The QR code can be displayed for users to scan with the MID mobile app.

Headers

3 active

Query Parameters

0 active

Request Body

JSON

Request Body Parameters

Parameter	Type	Required	Description
`clientId`	string	Yes	Your unique client identifier
`recipient`	string	Yes	User’s mobile number (E.164 format)
`intent`	string	Yes	Purpose: `login`, `payment`, `consent`
`callbackUrl`	string	Yes	URL to receive authentication result
`metadata`	object	No	Additional context data

Response


{
  "code": 201,
  "error": false,
  "message": "Consent session created",
  "data": {
    "sessionId": "sess_abc123def456",
    "qrCode": "data:image/png;base64,iVBORw0KGgo...",
    "qrData": "mid://auth?session=sess_abc123def456",
    "expiresAt": "2025-12-18T12:05:00Z",
    "status": "pending"
  }
}

Retrieve the current status of a consent session.

GET

https://sandbox.api.mobid.io/v1/consents/auth/:sessionId

Check the status of an authentication consent session. Use this to poll for approval status.

Headers

1 active

Query Parameters

1 active

Response Status Values

Status	Description
`pending`	Session created, waiting for user
`scanned`	QR code scanned, authentication in progress
`approved`	User approved the authentication
`rejected`	User rejected the request
`expired`	Session timed out (5 minutes)

FIDO/WebAuthn

Begin Registration

Start the FIDO2 credential registration process for a user.

POST

https://sandbox.api.mobid.io/v1/fido/register/begin

Generates WebAuthn registration options for a new credential. The response contains the challenge and parameters needed by the authenticator.

Headers

3 active

Query Parameters

0 active

Request Body

JSON

Response


{
  "code": 200,
  "error": false,
  "message": "Registration options generated",
  "data": {
    "challenge": "randomChallengeBase64Encoded",
    "rp": {
      "name": "MID - Mobile Identity",
      "id": "mobid.io"
    },
    "user": {
      "id": "dXNyXzEyMzQ1Njc4OQ==",
      "name": "user@example.com",
      "displayName": "John Doe"
    },
    "pubKeyCredParams": [
      { "type": "public-key", "alg": -7 },
      { "type": "public-key", "alg": -257 }
    ],
    "timeout": 60000,
    "attestation": "none",
    "authenticatorSelection": {
      "authenticatorAttachment": "platform",
      "residentKey": "preferred",
      "userVerification": "required"
    }
  }
}

Complete Registration

Complete the FIDO2 registration with the authenticator’s response.

POST

https://sandbox.api.mobid.io/v1/fido/register/complete

Verifies the authenticator's attestation response and stores the credential.

Headers

3 active

Query Parameters

0 active

Request Body

JSON

Begin Authentication

Start FIDO2 authentication for an existing user.

POST

https://sandbox.api.mobid.io/v1/fido/authenticate/begin

Generates WebAuthn authentication options. Returns available credentials for the user.

Headers

2 active

Query Parameters

0 active

Request Body

JSON

Device Management

Register Device

POST

https://sandbox.api.mobid.io/v1/devices

Registers a new device with a cryptographic fingerprint. Rate limited to 10 registrations per hour per IP.

Headers

2 active

Query Parameters

0 active

Request Body

JSON

Get Device Status

Check the activation status of a registered device.

GET

https://sandbox.api.mobid.io/v1/devices/:deviceId/status

Returns the current status and capabilities of a registered device.

Headers

2 active

Query Parameters

0 active

Client Management

Create Client

POST

https://sandbox.api.mobid.io/v1/clients

Creates a new client account and generates API credentials. Store the secret securely - it won't be shown again.

Headers

1 active

Query Parameters

0 active

Request Body

JSON

Response


{
  "code": 201,
  "error": false,
  "message": "Client created successfully",
  "data": {
    "clientId": "cli_abc123def456",
    "apiKey": "mk_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    "secret": "sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "callbackUrl": "https://your-app.com/webhooks/mid",
    "usage": {
      "auth": 0,
      "consent": 0,
      "profileUpdate": 0
    },
    "createdAt": "2025-12-18T10:00:00Z"
  }
}

⚠️

Store Your Credentials Securely

The secret is only shown once. Store it in a secure environment variable or secrets manager.

Enrollments

Start Enrollment

Begin the user enrollment process with OTP verification.

POST

https://sandbox.api.mobid.io/v1/enrollments

Initiates user enrollment with phone number verification. Rate limited to 5 attempts per device per hour.

Headers

3 active

Query Parameters

0 active

Request Body

JSON

Verify Enrollment

Complete enrollment with the OTP code.

POST

https://sandbox.api.mobid.io/v1/enrollments/:id/verify

Verifies the OTP and completes the enrollment process.

Headers

3 active

Query Parameters

0 active

Request Body

JSON

QR Code Operations

Generate QR Code

Generate a QR code for a consent session.

GET

https://sandbox.api.mobid.io/v1/consents/qr/:type/:sessionId

Returns a PNG image of the QR code for the specified session. Types: consent, auth, payment.

Headers

1 active

Query Parameters

2 active

Response

Returns image/png content type with the QR code image.

Rate Limits

Endpoint Category	Limit	Window
Authentication (`/auth/*`)	1,000 requests	15 minutes
FIDO (`/fido/*`)	1,000 requests	15 minutes
Consents (`/consents/*`)	1,000 requests	1 minute
Enrollments (`/enrollments/*`)	20 requests	1 hour
Device Registration	10 requests	1 hour
General	1,000 requests	15 minutes

ℹ️

Rate Limit Headers

Rate limit information is included in response headers:

RateLimit-Limit: Maximum requests allowed
RateLimit-Remaining: Requests remaining in window
RateLimit-Reset: Unix timestamp when the window resets

Error Responses

All errors follow a consistent format:


{
  "code": 400,
  "error": true,
  "message": "Descriptive error message",
  "details": "Additional context if available"
}

Common Error Codes

Code	Status	Description
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Insufficient permissions
404	Not Found	Resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Internal Error	Server-side error

Webhooks

Configure webhooks to receive real-time notifications:


{
  "event": "consent.approved",
  "timestamp": "2025-12-18T10:30:00Z",
  "data": {
    "sessionId": "sess_abc123",
    "userId": "usr_123456789",
    "status": "approved"
  },
  "signature": "sha256_hmac_signature"
}

Event Types

Event	Description
`consent.created`	New consent session created
`consent.scanned`	QR code scanned by user
`consent.approved`	User approved authentication
`consent.rejected`	User rejected request
`consent.expired`	Session timed out
`device.registered`	New device registered
`device.deregistered`	Device removed
`enrollment.completed`	User enrollment finished

API Reference

Authentication

Endpoints Overview

Consent Sessions

Create Authentication Consent

Headers

Query Parameters

Request Body

Request Body Parameters

Response

Get Consent Status

Headers

Query Parameters

Response Status Values

FIDO/WebAuthn

Begin Registration

Headers

Query Parameters

Request Body

Response

Complete Registration

Headers

Query Parameters

Request Body

Begin Authentication

Headers

Query Parameters

Request Body

Device Management

Register Device

Headers

Query Parameters

Request Body

Get Device Status

Headers

Query Parameters

Client Management

Create Client

Headers

Query Parameters

Request Body

Response

Enrollments

Start Enrollment

Headers

Query Parameters

Request Body

Verify Enrollment

Headers

Query Parameters

Request Body

QR Code Operations

Generate QR Code

Headers

Query Parameters

Response

Rate Limits

Error Responses

Common Error Codes

Webhooks

Event Types