API Reference: Gate Identity & Access

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

This API is divided into two logical parts:

Identity Management: Tenant-scoped proxy to Kratos Admin API for managing end-users.
Access & Authorization: Core services for token exchange and permission checks.

Access & Authorization

Create Access Token

POST /v1/gate/tokens

Exchanges a long-lived Gate API key for a short-lived access token that you can attach to backend or CLI requests.

Request Body

Field	Type	Required	Description
`api_key`	`string`	Yes	Your Gate API key (`vrn_gate_*`).
`subject`	`string`	Yes	ID of the user or service account this token represents.
`scopes`	`string[]`	No	Optional list of scopes to narrow the token (e.g. `['gate.tokens.read']`).
`ttl_seconds`	`number`	No	Custom lifetime in seconds (default 3600, max 86400).

Example Request & Response

curl -X POST https://api.vernesoft.com/v1/gate/tokens \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "vrn_gate_test_sk_123",
    "subject": "usr_123",
    "scopes": ["gate.tokens.read"],
    "ttl_seconds": 3600
  }'

{
  "access_token": "gat_test_at_abc123",
  "expires_at": "2026-03-17T12:00:00Z",
  "subject": "usr_123",
  "tenant_id": "ten_001"
}

Introspect Token

POST /v1/gate/tokens/introspect

Validates a Gate access token and returns its decoded attributes.

Request Body

Field	Type	Required	Description
`access_token`	`string`	Yes	The token you want to introspect.

Example Request & Response

curl -X POST https://api.vernesoft.com/v1/gate/tokens/introspect \
  -H 'Authorization: Bearer vrn_gate_test_sk_123' \
  -H 'Content-Type: application/json' \
  -d '{
    "access_token": "gat_test_at_abc123"
  }'

{
  "active": true,
  "subject": "usr_123",
  "tenant_id": "ten_001",
  "scopes": ["gate.tokens.read"],
  "expires_at": "2026-03-17T12:00:00Z"
}

Authorize Action

POST /v1/gate/authorize

Asks Gate whether a given subject is allowed to perform an action on a specific resource. This is the core building block for enforcing authorization in your services.

Request Body

Field	Type	Required	Description
`subject`	`string`	Yes	ID of the user or service account (e.g. `usr_123`).
`action`	`string`	Yes	Action being performed (e.g. `relay.messages.read`).
`resource`	`string`	Yes	Resource identifier (e.g. `tenant:ten_001` or `relay:key:key_123`).
`context`	`object`	No	Optional extra attributes for policy evaluation.

Example Request & Response

curl -X POST https://api.vernesoft.com/v1/gate/authorize \
  -H 'Authorization: Bearer vrn_gate_test_sk_123' \
  -H 'Content-Type: application/json' \
  -d '{
    "subject": "usr_123",
    "action": "relay.messages.read",
    "resource": "tenant:ten_001"
  }'

{
  "allowed": true,
  "decision_id": "dec_9f8a7c",
  "reason": "subject has role=admin on tenant:ten_001"
}

Error Format

Gate Identity uses the standard Verne error envelope:

{
  "error": {
    "code": "invalid_token",
    "message": "Token is expired or malformed.",
    "request_id": "req_abc123"
  }
}

Include the request_id when contacting support for faster resolution.