Theme

AUTH API Reference ​

Complete API documentation for Authentication.

Quick Start ​

Authentication ​

Choose authentication based on your use case:

User-Connected Apps (De.auth):

http
de-auth-token: YOUR_AUTH_TOKEN
de-user-agent: YOUR_USER_AGENT
de-auth-service: YOUR_SERVICE_NAME

Server-to-Server / Connectors:

http
Authorization: Bearer <ACCESS_TOKEN>

→ Authentication Guide

Base URL ​

https://auth.dedot.io/v1/auth

API Categories ​

Utilities ​

1 endpoint available

General Authentication ​

6 endpoints available

Sign In ​

http
POST /v1/signin
Content-Type: application/json
de-user-agent: Mobile App v1.0
de-auth-service: MyService

{
  "phone": "+1234567890",
  "device": {
    "platform": "iOS",
    "model": "iPhone 13"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "ip": "192.168.1.1"
  }
}

Response:

json
{
  "error": false,
  "status": "AUTH::UPN_SIGNIN",
  "message": "A phone number verification code is sent to user via sms",
  "next": "verify"
}

Phone Number Verification ​

http
POST /v1/verification
Content-Type: application/json
de-user-agent: Mobile App v1.0
de-auth-service: MyService

{
  "phone": "+1234567890",
  "pvc": 123456
}

Response for New User:

json
{
  "error": false,
  "status": "AUTH::PVC_VERIFIED",
  "next": "create-account"
}

Response for Existing User:

json
{
  "error": false,
  "status": "AUTH::SUCCEED",
  "next": "grantaccess",
  "ctoken": "ENCODED_CONNECTION_TOKEN",
  "deviceId": "DEVICE_IDENTIFIER"
}

Set Account ​

http
POST /v1/set-account
Content-Type: application/json
de-user-agent: Mobile App v1.0
de-auth-service: MyService

{
  "phone": "+1234567890",
  "firstName": "John",
  "lastName": "Doe",
  "agreeTerms": true,
  "type": "PERSONAL",
  "photo": "base64_encoded_image_data",
  "newsletters": true,
  "country": {
    "code": "US",
    "name": "United States"
  },
  "device": {
    "platform": "iOS",
    "model": "iPhone 13"
  }
}

Response:

json
{
  "error": false,
  "status": "AUTH::SUCCEED",
  "next": "grantaccess",
  "ctoken": "ENCODED_CONNECTION_TOKEN",
  "deviceId": "DEVICE_IDENTIFIER"
}

Change Phone Number ​

http
PUT /v1/change-phone
Content-Type: application/json
de-user-agent: Mobile App v1.0
de-auth-service: MyService

{
  "phone": "+1234567890",
  "new_phone": "+0987654321",
  "country": {
    "code": "US",
    "name": "United States"
  }
}

Response:

json
{
  "error": false,
  "status": "AUTH::UPN_SIGNIN",
  "message": "A phone number verification code is sent to user via sms",
  "next": "verify"
}

Resend Verification SMS ​

http
POST /v1/resend/sms
Content-Type: application/json
de-user-agent: Mobile App v1.0
de-auth-service: MyService

{
  "phone": "+1234567890"
}

Response:

json
{
  "error": false,
  "status": "AUTH::PVC_SENT",
  "message": "SMS resent",
  "delay": 120
}

Sign Out ​

http
GET /v1/signout?allDevices=false
Content-Type: application/json
de-auth-token: YOUR_AUTH_TOKEN
de-user-agent: Mobile App v1.0
de-auth-service: MyService

Response:

json
{
  "error": false,
  "status": "AUTH::SIGNED_OUT",
  "message": "Signed Out",
  "next": "signin"
}

Response Format ​

All API responses follow this structure:

typescript
interface APIResponse<T> {
  error: boolean;
  status: string;
  message?: string;
  data?: T;
}

Success Response ​

json
{
  "error": false,
  "status": "SUCCESS",
  "data": { ... }
}

Error Response ​

json
{
  "error": true,
  "status": "ERROR_CODE",
  "message": "Human-readable error message"
}

Common Error Codes ​

Status CodeDescription
SUCCESSRequest completed successfully
NOT_FOUNDResource not found (404)
UNAUTHORIZEDAuthentication failed (401)
FORBIDDENInsufficient permissions (403)
VALIDATION_ERRORInvalid request data (400)
INTERNAL_ERRORServer error (500)

Rate Limits ​

Standard Rate Limits:

  • 1000 requests per hour
  • 100 requests per minute (burst)

Rate limit headers:

http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

When rate limit is exceeded, you'll receive a 429 Too Many Requests response.

Pagination ​

List endpoints support pagination:

http
GET /v1/auth/resource?page=1&limit=50

Response includes pagination metadata:

json
{
  "error": false,
  "status": "SUCCESS",
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 237,
    "pages": 5
  }
}

Helpful Resources ​

Service OverviewAuthentication GuideReport Issues

Need help? Check our Developer Portal or contact support.