Developer docs

API integration guide

Auth-One provides a complete REST API for authentication, authorization, multi-app management, and third-party login. Follow this guide to complete your first request in minutes.

Integration guide API reference

Official API base URL

Defaults to the deploy-time setting NUXT_PUBLIC_DOCS_API_BASE_URL ; if unset, it uses NUXT_PUBLIC_API_BASE_URL . Changes here only update local documentation examples and do not change server configuration.

Overview

All endpoints are served over HTTP/HTTPS with JSON request and response bodies. Confirm the following before integrating:

Base URL	`https://gateway.mdsauth.com`
API version	`v1 (path prefix /api/v1)`
Content-Type	`application/json`
Authentication	`JWT Bearer / HMAC signature`

Common response format

Success response

{ "data": {} // or [] }

Error response

{ "error": "error message" }

Paginated response

{ "data": [], "total": 100, "page": 1, "page_size": 10 }

Authentication

Auth-One provides two authentication methods: one for end-user APIs and one for third-party open APIs.

JWT authentication

Use this for APIs that require a user identity. After sign-in, send the access token in the request header:

Authorization: Bearer <token>

API client authentication

Used when third-party systems call open APIs (/api/v1/external/*). Compute an HMAC with the Secret; do not send the Secret in headers:

X-Tenant-ID: <tenant_id>X-App-ID: <app_id>X-API-Key: <api_key>X-Timestamp: <unix_seconds>X-Nonce: <nonce>X-Signature: <hex_hmac>

The API Secret is returned only when a client is created or regenerated. Save it immediately. Open APIs require HTTPS and must never send the plaintext Secret.

Don't have client credentials yet? Submit integration request, and we will create and deliver credentials after approval.

Quick start

The following curl examples walk through the full flow. They use the official API base URL configured above, which you can override or reset at any time.

Sign in a user and obtain an access token

curl

curl -X POST https://gateway.mdsauth.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "Admin@123456"}'

Call a user API with the token

curl

curl -X GET https://gateway.mdsauth.com/api/v1/users/me \
  -H "Authorization: Bearer <token>"

Call an open API with an HMAC signature

curl

curl -X GET https://gateway.mdsauth.com/api/v1/external/users/<user_id> \
  -H "X-Tenant-ID: <tenant_id>" \
  -H "X-App-ID: <app_id>" \
  -H "X-API-Key: <api_key>" \
  -H "X-Timestamp: <unix_seconds>" \
  -H "X-Nonce: <16-128_urlsafe>" \
  -H "X-Signature: <hex_hmac_sha256>"

Core API overview

The most common endpoint groups are listed below. For full request and response fields, see API reference

Authentication

POST	/api/v1/auth/register/send-code	Send registration email code
POST	/api/v1/auth/register	Register a new user
POST	/api/v1/auth/login	Sign in a user and obtain an access token

User

GET	/api/v1/users/me	Get the current user
PUT	/api/v1/users/me	Update current user (always returns 405 today)
PUT	/api/v1/users/me/password	Change the current user's password

Application and client management

GET	/api/v1/applications	List applications
POST	/api/v1/api-clients	Create API client (Secret is returned only once)
POST	/api/v1/api-clients/{id}/regenerate-secret	Regenerate client secret
POST	/api/v1/api-clients/validate	Validate client credentials

Integration requests (public, no authentication required)

POST

/api/v1/access-requests

Open APIs (HMAC signature authentication)

GET	/api/v1/external/users/{id}	Get basic user information
POST	/api/v1/external/users/check-access	Check whether a user can access an application
POST	/api/v1/external/third-party/find-user	Find a user by third-party account

Health check

GET

/health

Error codes

On error the API returns the corresponding HTTP status code, and the response body includes error describing the reason.

Status code	Description
400	Invalid request parameters
401	Unauthenticated, invalid signature, or replayed nonce
403	Insufficient permission or caller IP not on the allowlist
404	Resource not found
409	A pending access request already exists for this email
426	Open APIs require HTTPS
429	Too many requests (rate limit reached)
500	Internal server error

Conventions and rate limits

Rate limiting

Each IP has a maximum of 100 requests per minute, after which a 429 status code is returned.

Pagination parameters

page starts from 1, page_size defaults to 20, and the maximum is 100.

Time format

All time fields use ISO 8601 format (with time zone).

ID format

All ID fields use UUID format.

Delete operations

Most delete endpoints return HTTP 204 with no response body.

Password security

All password endpoints use encrypted transport and store passwords as bcrypt hashes.

Implement exponential backoff on the client: wait briefly after a 429 response before retrying so you do not keep hitting the rate limit.