Documentation

Deposure is a secure tunneling platform (similar to ngrok) that exposes local services to the public internet over HTTPS. It’s ideal for testing webhooks, sharing live previews, and remote debugging.

The API is RESTful, uses JSON for request/response bodies (unless noted), and relies on standard HTTP verbs and status codes. Environments include test and live; your credentials determine which mode is active.

Not a Developer?

Use no‑code options or partner apps to get started quickly, configure basic tunnels, and manage domains without writing code.

BASE URL

https://api.deposure.com

Authentication

Authenticate with your email and password to obtain a session token. Pass this token in the Authorization header for all subsequent requests. Tokens are scoped to your account and may expire; if a request returns 401 Unauthorized, re‑authenticate.

Header format: Authorization: Bearer <TOKEN>
Environment: The same endpoint is used for test/live; your credentials decide the mode.
Error codes: 400 (validation), 401 (invalid/expired token), 429 (rate limit), 5xx (service).

Login – Create Session

Endpoint

POST /auth/sessions

Payload

{ "email": "[email protected]", "password": "secret" }

cURL

curl -X POST https://api.deposure.com/auth/sessions \
 -H "Content-Type: application/json" \
 -d '{"email":"[email protected]","password":"secret"}'

Successful Response (200)

{
  "token": "<JWT>",
  "token_type": "Bearer",
  "expires_in": 3600
}

User Account

Retrieve metadata about the currently authenticated account, including contact email, available features, and plan limits. Use this endpoint to confirm authentication, check domain quota, and discover enabled capabilities (e.g., custom SSL, error pages).

Caching: Safe to cache short‑term for UI; avoid long‑term caching for security.
Use cases: Show account name, plan, and remaining quotas in dashboards.

Get Account

GET /v2/account

Headers: Authorization: Bearer <TOKEN>

{
  "id": "acc_123",
  "email": "[email protected]",
  "plan": "pro",
  "features": { "custom_domains": true, "custom_ssl": true, "custom_errors": true },
  "limits": { "tunnels_max": 10, "domains_max": 25 }
}

Tunnels – Listing

List all tunnels owned by your account. Each item includes identifiers, current status, assigned domains, and timestamps. Use this to build dashboards, calculate uptime, or locate a tunnel’s app_id for management actions.

Method: GET /v2/tunnel
Auth: Bearer token
Notes: Results may be paginated in future versions; handle arrays defensively.

Example

curl -H "Authorization: Bearer <TOKEN>" https://api.deposure.com/v2/tunnel

[
  {
    "app_id": "app_abc",
    "name": "staging-api",
    "status": "online",
    "public_url": "https://staging.example.dev",
    "domains": ["staging.example.dev"],
    "created_at": "2025-05-01T10:12:00Z"
  }
]

Tunnels – Creation

Create a new tunnel with a human‑friendly name. Names must be unique per account. After creation, you may bind domains, upload SSL, and attach rules. Common use cases include staging previews and webhook endpoints.

Method: POST /v2/tunnel
Payload: { "name": "my-tunnel" }
Errors: 409 if name is already taken; 422 for invalid name format.

Example

curl -X POST https://api.deposure.com/v2/tunnel \
 -H "Authorization: Bearer <TOKEN>" \
 -H "Content-Type: application/json" \
 -d '{"name":"my-tunnel"}'

{
  "app_id": "app_xyz",
  "name": "my-tunnel",
  "status": "online",
  "public_url": "https://my-tunnel.deposure.run"
}

Tunnels – Terminate

Gracefully terminate an active tunnel session. Existing in‑flight connections are dropped. Use this when rotating environments or freeing resources. The tunnel record may remain for audit/history until deleted via Delete Tunnel.

Method: DELETE /v1/terminate-connection
Payload: { "app_id": "<id>" }
Returns: confirmation with termination timestamp.

Example

curl -X DELETE https://api.deposure.com/v1/terminate-connection \
 -H "Authorization: Bearer <TOKEN>" \
 -H "Content-Type: application/json" \
 -d '{"app_id":"app_xyz"}'

{ "terminated": true, "app_id": "app_xyz", "at": "2025-08-18T12:00:00Z" }

Tunnels – Get Info

Retrieve health and runtime metrics for a specific tunnel by its identifier. Useful for monitoring, alerting, and status pages.

Method: GET /v1/health/tunnel/{id}
Params: id – tunnel identifier
Returns: status, latency, last heartbeat, assigned domains.

Example

curl -H "Authorization: Bearer <TOKEN>" https://api.deposure.com/v1/health/tunnel/app_xyz

{
  "app_id": "app_xyz",
  "status": "online",
  "latency_ms": 42,
  "last_heartbeat": "2025-08-18T11:58:20Z",
  "domains": ["my-tunnel.deposure.run", "api.example.com"]
}

Tunnels – Rename

Update a tunnel’s display name. This does not change existing public URLs or domain bindings. Use this to keep naming consistent across environments.

Method: PATCH /apps
Payload: { "app_id": "<id>", "new_name": "staging-v2" }
Errors: 409 if new_name collides with another tunnel name.

Example

curl -X PATCH https://api.deposure.com/apps \
 -H "Authorization: Bearer <TOKEN>" \
 -H "Content-Type: application/json" \
 -d '{"app_id":"app_xyz","new_name":"staging-v2"}'

{ "app_id": "app_xyz", "name": "staging-v2" }

Tunnels – Delete

Permanently delete a tunnel configuration and its historical metadata. Ensure the tunnel is terminated first to avoid dangling sessions. This action cannot be undone.

Method: DELETE /apps
Payload: { "app_id": "<id>" }
Impact: removes rules, domain bindings, and error page links for this tunnel.

Example

curl -X DELETE https://api.deposure.com/apps \
 -H "Authorization: Bearer <TOKEN>" \
 -H "Content-Type: application/json" \
 -d '{"app_id":"app_xyz"}'

{ "deleted": true, "app_id": "app_xyz" }

Tunnel Rules

Rules let you control access (e.g., IP allow/deny) and behavior at the edge. Attach rules to a tunnel using its app_id. Typical scenarios include staging environments restricted to office IP ranges.

Types: IP (CIDR or single IP). More types may be added in future versions.
Order: Rules are evaluated in a defined order; specific allow/deny wins over broad ranges.
Conflicts: If both allow and deny match, the most specific rule takes precedence.

Add Rule

POST /apps/rules Payload: { "app_id": "app_xyz", "rule_type": "IP", "rule_value": "203.0.113.0/24" }

curl -X POST https://api.deposure.com/apps/rules -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" -d '{"app_id":"app_xyz","rule_type":"IP","rule_value":"203.0.113.0/24"}'

Delete Rule

DELETE /apps/rules Payload: { "app_id": "app_xyz", "rule_type": "IP", "rule_value": "203.0.113.0/24" }

curl -X DELETE https://api.deposure.com/apps/rules -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" -d '{"app_id":"app_xyz","rule_type":"IP","rule_value":"203.0.113.0/24"}'

Domain Management

Bind your own domains to tunnels to get branded URLs. After adding a domain, point its DNS record (typically CNAME) to the target shown in the response or dashboard. For production, combine with a custom SSL certificate for full trust.

Add Domain: link a domain to a specific tunnel_id.
List Domains: view all domains across the account and their states (pending, verified, active).
Delete Domain: remove binding; SSL association (if any) will be released.

Add Domain

POST /v2/domain Payload: { "domain": "api.example.com", "tunnel_id": "app_xyz" }

curl -X POST https://api.deposure.com/v2/domain -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" -d '{"domain":"api.example.com","tunnel_id":"app_xyz"}'

{ "domain_id": "dom_123", "status": "pending_dns", "required_cname": "my-tunnel.deposure.run" }

List Domains

GET /v2/account/domains curl -H "Authorization: Bearer <TOKEN>" https://api.deposure.com/v2/account/domains

[
  { "domain_id": "dom_123", "domain": "api.example.com", "status": "active", "tunnel_id": "app_xyz" }
]

Delete Domain

DELETE /apps/domains Payload: { "domain_id": "dom_123", "domain_name": "api.example.com", "app_id": "app_xyz" }

curl -X DELETE https://api.deposure.com/apps/domains -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" -d '{"domain_id":"dom_123","domain_name":"api.example.com","app_id":"app_xyz"}'

{ "deleted": true, "domain_id": "dom_123" }

SSL Management

Upload your own TLS/SSL certificate and key, then assign it to a verified domain. Custom SSL ensures browsers see your organization in the certificate chain and prevents warnings. Supported formats include PEM for certificates and unencrypted PKCS#1/PKCS#8 for private keys.

Upload: multipart certificate and private_key fields.
Assign: reference the returned cert_id and target domain_id.
Validation: server verifies key/cert pair and expiration.

Upload Certificate

POST /v2/ssl-certificates/upload

curl -X POST https://api.deposure.com/v2/ssl-certificates/upload -H "Authorization: Bearer <TOKEN>" -F "certificate=@/path/cert.pem" -F "private_key=@/path/key.pem"

{ "cert_id": "cert_987", "fingerprint": "AF:12:...", "expires_at": "2026-06-01T00:00:00Z" }

Assign SSL to Domain

PATCH /v2/ssl-certificates Payload: { "new_cert_id": "cert_987", "domain_id": "dom_123" }

curl -X PATCH https://api.deposure.com/v2/ssl-certificates -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" -d '{"new_cert_id":"cert_987","domain_id":"dom_123"}'

{ "domain_id": "dom_123", "cert_id": "cert_987", "active": true }

Custom Error Pages

Upload branded HTML templates for HTTP error responses (e.g., 404, 502) on a per‑tunnel basis. This helps provide a cohesive user experience during outages or maintenance. Templates should be compact, self‑contained HTML files without external blocking dependencies.

Supported codes: 400–599 (common ones: 403, 404, 500, 502, 503).
Size limits: keep under typical edge size constraints; inline CSS recommended.
Fallback: if no custom template exists, a default Deposure page is returned.

Add Custom Error Page

POST /apps/custom/errors multipart/form-data: { app_id, error_code, template=@/path/404.html }

curl -X POST https://api.deposure.com/apps/custom/errors -H "Authorization: Bearer <TOKEN>" -F "app_id=app_xyz" -F "error_code=404" -F "template=@/path/404.html"

{ "uploaded": true, "app_id": "app_xyz", "error_code": 404 }