DIDHub Docs

Appearance

Security & data handling ​

This page covers how the DIDHub API protects credentials in transit and at rest, how authentication scopes work, what your responsibilities are when storing personal data, and how to operate the API safely in automation.

Transport security ​

All API traffic terminates on https://api.didhub.io. Plain HTTP is not accepted. TLS 1.2+ is required; modern ciphers are preferred. Certificates are managed by Cloudflare and auto-renew.

The dashboard at https://dashboard.didhub.io (alias: https://dash.didhub.io) uses the same hardened endpoint set.

WARNING

Never send API keys, session cookies, or personal data over plain HTTP — even to localhost. If you need to test against a local proxy, terminate TLS at the proxy.

Authentication ​

Two schemes are supported. Most endpoints accept either.

Issued by POST /v1/auth/login and POST /v1/auth/verify-email. HMAC-signed, marked HttpOnly, Secure, and SameSite=Lax. Used by the DIDHub dashboard SPA.

  • Sessions expire by default after the rolling inactivity window. Active use refreshes the window.
  • Sessions can be revoked from Settings → Security or via POST /v1/auth/sessions/{id}/revoke.
  • POST /v1/auth/sessions/revoke-others invalidates every session except the calling one — useful after a suspected compromise.
  • GET /v1/auth/login-history returns recent sign-in attempts (successful and failed) so you can audit account activity.

Bearer API key ​

Issued via POST /v1/api-keys and presented as Authorization: Bearer didhub_live_….

  • The raw key is returned once at creation time in the key field of the response. We store only a hash — there is no way to retrieve it later.
  • Treat keys like passwords: store them in a secrets manager, never check them into git, rotate periodically.
  • Revoke compromised keys with DELETE /v1/api-keys/{id}. Revocation is immediate.
  • Each key carries a scopes field (currently ["*"] — granular scopes are on the roadmap).

TIP

Programmatic API keys are currently in beta. Email support@didhub.io to enable them for your account.

Multi-factor authentication ​

Owners and admins are strongly encouraged to enable TOTP MFA via POST /v1/auth/mfa/setup-start. Once enabled, every interactive sign-in (including OAuth) requires a second factor — programmatic API keys are unaffected.

Idempotency ​

Mutating endpoints (POST, PATCH, DELETE) accept an optional Idempotency-Key header. Re-sending the same key with the same body within 24 hours returns the original response without re-executing the action. Different bodies under the same key return 422.

Recommended pattern: generate a UUIDv4 per logical operation in your code and re-use it when retrying after a timeout.

Rate limits ​

Rate limits are enforced per-account, with separate budgets for read and mutating endpoints. Exceeded limits return:

HTTP/1.1 429 Too Many Requests
Retry-After: <seconds>

Back off for the indicated duration before retrying.

Personal data — your responsibilities ​

Some endpoints handle data your end-users entrust to you:

  • /v1/compliance/end-users — names, dates of birth, addresses, document numbers
  • /v1/compliance/documents — passport scans, utility bills, business registrations
  • /v1/compliance/bundles — packaged end-user + documents submitted to a regulator
  • /v1/cdrs — caller / callee numbers, which can identify individuals

You are the data controller for this information under GDPR, CCPA, and equivalent regimes. DIDHub processes it on your behalf as a data processor under our Data Processing Addendum (linked from your billing dashboard).

Practical guidance:

  1. Collect only what a regulator actually requires for the country / number type — there's no benefit to over-collection.
  2. Honor erasure requests by deleting the end-user record (DELETE /v1/compliance/end-users/{id}) — this also removes attached documents that aren't referenced by another bundle.
  3. Don't share raw document numbers or scans in tickets, chat tools, or screenshots. If support needs to verify a bundle, give them the bundle ID — we look up the record on our side.
  4. CDR caller/callee numbers should be treated as personal data. Restrict who can read /v1/cdrs in your organization.

Data at rest ​

  • All sensitive fields (SIP gateway passwords, document binaries, MFA secrets) are encrypted at rest.
  • API keys are stored hashed; the raw value is unrecoverable after creation.
  • Database backups are encrypted and retained per the DPA.

Retention ​

  • CDRs are retained for the lifetime of your account so you can reconcile billing.
  • Closed accounts are anonymized 30 days after closure, after which billing-related records remain for the period required by tax law in the relevant jurisdiction (typically 7 years).
  • Compliance documents are retained for as long as the bundle they belong to is referenced by an active number, plus the retention window required by the regulator (typically 12–24 months after number release).
  • Login history is retained for 90 days.

To request a custom retention policy or earlier deletion, contact privacy@didhub.io.

Reporting a vulnerability ​

Found a security issue? Email security@didhub.io. We acknowledge within one business day and aim to triage within five.

Please do not include exploit details or proof-of-concept payloads in initial reports. We'll request what we need over an encrypted channel.

Out-of-scope categories (we won't reward but will still appreciate the report):

  • DoS against public endpoints
  • Self-XSS that requires the victim to paste content into a console
  • Reports requiring physical or social-engineering access
  • Missing best-practice headers without a concrete exploit