de.auth API Reference

Complete API reference for De. authentication and user management service.

Base URL

Production: https://auth.dedot.io/v1
Development: https://auth-dev.dedot.io/v1

Authentication

All authenticated endpoints require Bearer token in Authorization header:

Authorization: Bearer <access_token>

Phone Authentication

Initiate Phone Auth

Send verification code to phone number.

http

POST /auth/phone/initiate
Content-Type: application/json

{
  "phone": "+1234567890",
  "channel": "sms"
}

Response: 200 OK

json

{
  "success": true,
  "sessionId": "sess_abc123",
  "expiresIn": 300
}

Verify Phone Code

Verify phone with SMS code.

http

POST /auth/phone/verify
Content-Type: application/json

{
  "phone": "+1234567890",
  "code": "123456",
  "sessionId": "sess_abc123"
}

Response: 200 OK

json

{
  "success": true,
  "accessToken": "eyJhbGci...",
  "refreshToken": "refresh_...",
  "expiresIn": 3600,
  "user": { /* User object */ }
}

Email Authentication

Register

Create new user account.

http

POST /auth/email/register
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "SecurePass123!",
  "name": "John Doe",
  "userType": "client"
}

Response: 201 Created

json

{
  "success": true,
  "user": { /* User object */ },
  "verificationToken": "verify_abc123"
}

Verify Email

Verify email address.

http

POST /auth/email/verify
Content-Type: application/json

{
  "token": "verify_abc123"
}

Response: 200 OK

json

{
  "success": true,
  "user": { /* User object */ }
}

Authenticate with email and password.

http

POST /auth/email/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "SecurePass123!"
}

Response: 200 OK

json

{
  "success": true,
  "accessToken": "eyJhbGci...",
  "refreshToken": "refresh_...",
  "expiresIn": 3600,
  "user": { /* User object */ }
}

Forgot Password

Request password reset.

http

POST /auth/email/forgot-password
Content-Type: application/json

{
  "email": "[email protected]"
}

Response: 200 OK

json

{
  "success": true,
  "message": "Password reset email sent"
}

Reset Password

Reset password with token.

http

POST /auth/email/reset-password
Content-Type: application/json

{
  "token": "reset_abc123",
  "newPassword": "NewPass123!"
}

Response: 200 OK

json

{
  "success": true,
  "message": "Password reset successful"
}

OAuth Authentication

Authorize

Initiate OAuth flow.

http

GET /auth/oauth/{provider}/authorize?redirect_uri={uri}

Providers: google, github, microsoft, apple

Response: 302 Redirect to provider authorization page

OAuth Callback

Exchange authorization code for token.

http

POST /auth/oauth/{provider}/callback
Content-Type: application/json

{
  "code": "AUTH_CODE",
  "redirectUri": "https://yourapp.com/callback"
}

Response: 200 OK

json

{
  "success": true,
  "accessToken": "eyJhbGci...",
  "refreshToken": "refresh_...",
  "expiresIn": 3600,
  "user": { /* User object */ }
}

Link OAuth Provider

Link OAuth account to existing user.

http

POST /auth/oauth/link
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "provider": "google",
  "code": "AUTH_CODE",
  "redirectUri": "https://yourapp.com/callback"
}

Response: 200 OK

json

{
  "success": true,
  "linkedProviders": ["email", "google"]
}

Unlink OAuth Provider

Remove OAuth provider from account.

http

DELETE /auth/oauth/unlink/{provider}
Authorization: Bearer <access_token>

Response: 200 OK

json

{
  "success": true,
  "remainingProviders": ["email"]
}

Session Management

Refresh Token

Get new access token.

http

POST /auth/refresh
Content-Type: application/json

{
  "refreshToken": "refresh_abc123"
}

Response: 200 OK

json

{
  "success": true,
  "accessToken": "eyJhbGci...",
  "expiresIn": 3600
}

Validate Token

Check if access token is valid.

http

GET /auth/validate
Authorization: Bearer <access_token>

Response: 200 OK

json

{
  "valid": true,
  "user": { /* User object */ },
  "expiresAt": "2026-01-16T12:00:00Z"
}

Logout

Invalidate current session.

http

POST /auth/logout
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "refreshToken": "refresh_abc123"
}

Response: 200 OK

json

{
  "success": true,
  "message": "Logged out successfully"
}

List Sessions

Get all active sessions.

http

GET /auth/sessions
Authorization: Bearer <access_token>

Response: 200 OK

json

{
  "sessions": [
    {
      "id": "sess_123",
      "device": "Chrome on MacOS",
      "ip": "192.168.1.100",
      "lastActive": "2026-01-16T11:00:00Z",
      "current": true
    }
  ]
}

Revoke Session

Delete specific session.

http

DELETE /auth/sessions/{sessionId}
Authorization: Bearer <access_token>

Response: 200 OK

json

{
  "success": true,
  "message": "Session revoked"
}

User Management

Get Current User

Get authenticated user profile.

http

GET /users/me
Authorization: Bearer <access_token>

Response: 200 OK

json

{
  "id": "usr_123456",
  "email": "[email protected]",
  "phone": "+1234567890",
  "name": "John Doe",
  "avatar": "https://cdn.dedot.io/avatars/usr_123456.jpg",
  "userType": "client",
  "verified": true,
  "createdAt": "2026-01-10T10:00:00Z",
  "metadata": { /* Custom data */ }
}

Get User by ID

Get specific user profile.

http

GET /users/{userId}
Authorization: Bearer <access_token>

Response: 200 OK

json

{
  "id": "usr_789",
  "name": "Jane Smith",
  "avatar": "https://cdn.dedot.io/avatars/usr_789.jpg",
  "userType": "agent",
  "verified": true,
  "public": { /* Public profile data */ }
}

Update Profile

Update user information.

http

PATCH /users/me
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "John Smith",
  "metadata": {
    "language": "es",
    "timezone": "Europe/Madrid"
  }
}

Response: 200 OK

json

{
  "success": true,
  "user": { /* Updated user object */ }
}

Upload Avatar

Upload profile picture.

http

POST /users/me/avatar
Authorization: Bearer <access_token>
Content-Type: multipart/form-data

file: <image_file>

Response: 200 OK

json

{
  "success": true,
  "avatarUrl": "https://cdn.dedot.io/avatars/usr_123456.jpg"
}

Search Users

Search for users.

http

GET /users/search?q={query}&type={userType}&limit={limit}&offset={offset}
Authorization: Bearer <access_token>

Response: 200 OK

json

{
  "users": [ /* Array of user objects */ ],
  "total": 50,
  "limit": 20,
  "offset": 0
}

Update Notification Settings

Configure notification preferences.

http

PATCH /users/me/settings/notifications
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "email": {
    "enabled": true,
    "orderUpdates": true,
    "marketing": false
  },
  "push": {
    "enabled": true,
    "orderUpdates": true
  }
}

Response: 200 OK

json

{
  "success": true,
  "settings": { /* Updated settings */ }
}

Update Privacy Settings

Configure privacy preferences.

http

PATCH /users/me/settings/privacy
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "profileVisibility": "public",
  "showEmail": false,
  "showPhone": false
}

Response: 200 OK

json

{
  "success": true,
  "settings": { /* Updated settings */ }
}

Delete Account

Permanently delete user account.

http

DELETE /users/me
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "password": "user_password",
  "confirmation": "DELETE_MY_ACCOUNT"
}

Response: 200 OK

json

{
  "success": true,
  "message": "Account deletion scheduled",
  "deletionDate": "2026-02-15T00:00:00Z"
}

Data Types

User Object

typescript

{
  id: string              // User ID (usr_*)
  email?: string          // Email address
  phone?: string          // Phone number
  name: string            // Full name
  avatar?: string         // Avatar URL
  userType: UserType      // User type
  verified: boolean       // Email/phone verified
  createdAt: string       // ISO 8601 timestamp
  updatedAt: string       // ISO 8601 timestamp
  metadata?: object       // Custom user data
}

UserType Enum

typescript

type UserType = 
  | 'client'    // End customer
  | 'agent'     // Delivery driver/field worker
  | 'lsp'       // Logistics service provider
  | 'csp'       // Commerce service provider
  | 'dev'       // Developer/integrator

Session Object

typescript

{
  id: string              // Session ID
  device: string          // Device description
  ip: string              // IP address
  lastActive: string      // ISO 8601 timestamp
  current: boolean        // Is current session
}

Error Responses

All endpoints return errors in this format:

json

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": { /* Additional error context */ }
  }
}

Common Error Codes

Code	HTTP Status	Description
`INVALID_REQUEST`	400	Malformed request or missing required parameters
`UNAUTHORIZED`	401	Invalid or expired access token
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`CONFLICT`	409	Resource already exists (e.g., email taken)
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INTERNAL_ERROR`	500	Internal server error

Authentication Errors

Code	Description
`INVALID_CREDENTIALS`	Email/password incorrect
`INVALID_CODE`	Verification code incorrect
`CODE_EXPIRED`	Verification code expired
`TOKEN_EXPIRED`	Access token expired
`TOKEN_INVALID`	Access token malformed
`SESSION_EXPIRED`	Session no longer valid

Rate Limits

Endpoint Group	Limit	Window
Authentication	10 requests	Per IP per 15 minutes
Token Refresh	5 requests	Per token per hour
Profile Updates	10 requests	Per user per hour
User Search	100 requests	Per user per hour
Avatar Upload	5 uploads	Per user per day

Rate limit headers included in responses:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1705405200

Webhooks

Subscribe to user events (requires workspace configuration):

Available Events

user.created - New user registered
user.updated - User profile updated
user.deleted - User account deleted
user.verified - User email/phone verified
session.created - New session started
session.expired - Session expired or logged out

Webhook Payload

json

{
  "event": "user.created",
  "timestamp": "2026-01-16T11:00:00Z",
  "data": {
    "user": { /* User object */ }
  }
}

SDKs & Libraries

Official SDKs available:

JavaScript/TypeScript: @de./sdk
React Native: @de./sdk-rn
Python: Coming soon
Go: Coming soon

Next Steps

Auth Overview Phone Auth Email Auth User Management

de.auth API Reference ​

Base URL ​

Authentication ​

Phone Authentication ​

Initiate Phone Auth ​

Verify Phone Code ​

Email Authentication ​

Register ​

Verify Email ​

Login ​

Forgot Password ​

Reset Password ​

OAuth Authentication ​

Authorize ​

OAuth Callback ​

Link OAuth Provider ​

Unlink OAuth Provider ​

Session Management ​

Refresh Token ​

Validate Token ​

Logout ​

List Sessions ​

Revoke Session ​

User Management ​

Get Current User ​

Get User by ID ​

Update Profile ​

Upload Avatar ​

Search Users ​

Update Notification Settings ​

Update Privacy Settings ​

Delete Account ​

Data Types ​

User Object ​

UserType Enum ​

Session Object ​

Error Responses ​

Common Error Codes ​

Authentication Errors ​

Rate Limits ​

Webhooks ​

Available Events ​

Webhook Payload ​

SDKs & Libraries ​

Next Steps ​

de.auth API Reference

Base URL

Authentication

Phone Authentication

Initiate Phone Auth

Verify Phone Code

Email Authentication

Register

Verify Email

Login

Forgot Password

Reset Password

OAuth Authentication

Authorize

OAuth Callback

Link OAuth Provider

Unlink OAuth Provider

Session Management

Refresh Token

Validate Token

Logout

List Sessions

Revoke Session

User Management

Get Current User

Get User by ID

Update Profile

Upload Avatar

Search Users

Update Notification Settings

Update Privacy Settings

Delete Account

Data Types

User Object

UserType Enum

Session Object

Error Responses

Common Error Codes

Authentication Errors

Rate Limits

Webhooks

Available Events

Webhook Payload

SDKs & Libraries

Next Steps