API Reference: Gate Identity

All Gate Identity endpoints are served from https://api.vernesoft.com.

Examples are shown as raw curl requests and as calls through the official SDKs — see Installation to set one up. SDK snippets assume an initialized verne client.

Every request requires a tenant API key in the Authorization header:

Authorization: Bearer vrn_gate_live_sk_9f8a7...

Identity Management

Tenant API keys can only access identities that belong to their own tenant. The Edge Gateway enforces this isolation — cross-tenant access is structurally impossible.

Create Identity

POST /v1/gate/identities

Creates a new end-user identity bound to your tenant.

Request body — Kratos-compatible identity object:

curl -X POST https://api.vernesoft.com/v1/gate/identities \
  -H 'Authorization: Bearer vrn_gate_live_sk_9f8a7...' \
  -H 'Content-Type: application/json' \
  -d '{
    "schema_id": "user",
    "traits": { "email": "user@example.com" },
    "credentials": {
      "password": { "config": { "password": "StrongPassword123!" } }
    },
    "state": "active"
  }'

Returns the created identity object (201 Created). Fires the identity.created webhook event.

Get Identity

GET /v1/gate/identities/{id}

Returns the full Kratos identity object. Includes traits, metadata_public, state, and credential metadata (no secrets).

curl https://api.vernesoft.com/v1/gate/identities/f47ac10b-... \
  -H 'Authorization: Bearer vrn_gate_live_sk_9f8a7...'

Update Identity

PATCH /v1/gate/identities/{id}

Updates traits or other mutable fields. Body is a JSON Patch (RFC 6902) — an array of operations applied to the identity object; fields not referenced by any operation are unchanged.

curl -X PATCH https://api.vernesoft.com/v1/gate/identities/f47ac10b-... \
  -H 'Authorization: Bearer vrn_gate_live_sk_9f8a7...' \
  -H 'Content-Type: application/json' \
  -d '[
    { "op": "replace", "path": "/traits/email", "value": "newemail@example.com" }
  ]'

Delete Identity

DELETE /v1/gate/identities/{id}

Permanently deletes the identity. Returns 204 No Content. Fires the identity.deleted webhook event.

curl -X DELETE https://api.vernesoft.com/v1/gate/identities/f47ac10b-... \
  -H 'Authorization: Bearer vrn_gate_live_sk_9f8a7...'

Activate / Deactivate Identity

PATCH /v1/gate/identities/{id}/state

Changes the identity state. An inactive identity cannot log in — Kratos rejects their credentials automatically.

curl -X PATCH https://api.vernesoft.com/v1/gate/identities/f47ac10b-.../state \
  -H 'Authorization: Bearer vrn_gate_live_sk_9f8a7...' \
  -H 'Content-Type: application/json' \
  -d '{ "state": "inactive" }'

Fires the identity.state_changed webhook event on success. See Custom Metadata for details.

Custom Metadata

GET  /v1/gate/identities/{id}/metadata
PATCH /v1/gate/identities/{id}/metadata

Read or merge-update the metadata_public JSON object attached to an identity. Pass null for a key to delete it.

See Custom Metadata for full documentation.

Session Management

GET    /v1/gate/identities/{id}/sessions
DELETE /v1/gate/identities/{id}/sessions
DELETE /v1/gate/sessions/{session_id}

List or revoke active sessions for an end-user. Tenant isolation is enforced — you can only manage sessions of identities that belong to your tenant.

See Session Management for the full reference including response format and integration examples.

Resend Verification Email

POST /v1/gate/identities/{id}/resend-verification

Triggers a new verification email for an unverified identity. The link is valid for the flow TTL configured in Kratos.

curl -X POST https://api.vernesoft.com/v1/gate/identities/f47ac10b-.../resend-verification \
  -H 'Authorization: Bearer vrn_gate_live_sk_9f8a7...'

Auth Flows

Self-service flows for end-users. All flow endpoints return a Kratos flow object containing UI nodes your frontend renders. See Settings Flow for the full flow lifecycle.

The login and registration flows also accept an X-Return-To header for post-flow redirect.

Tenant Settings

OIDC Providers

GET  /v1/gate/settings/oidc-providers
PUT  /v1/gate/settings/oidc-providers

Read or replace the list of social login providers enabled for your tenant. See Social Auth for configuration details.

Security Settings

GET /v1/gate/settings/security
PUT /v1/gate/settings/security

Read or update per-tenant security feature flags.

curl -X PUT https://api.vernesoft.com/v1/gate/settings/security \
  -H 'Authorization: Bearer vrn_gate_live_sk_9f8a7...' \
  -H 'Content-Type: application/json' \
  -d '{ "passwordless_enabled": true, "mfa_enabled": false }'

Webhooks

GET    /v1/gate/settings/webhooks
POST   /v1/gate/settings/webhooks
PATCH  /v1/gate/settings/webhooks/{id}
DELETE /v1/gate/settings/webhooks/{id}

Manage webhook endpoints that receive real-time identity event notifications. See Webhooks for the full reference including payload format and signature verification.

Tokens & Authorization

See Access & Authorization for the full token lifecycle reference.

Error Format

All errors use the same envelope:

{
  "error": "description of what went wrong"
}

Kratos flow errors return the full flow object with a populated ui.messages array — render these to guide the end-user.