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_...`).
`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

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

Response

{
  "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.

active is false when the token is unknown, expired, belongs to another tenant, or its subject is an end user you have deactivated or deleted. A deactivated user's tokens become active again when you reactivate them.

Request Body

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

Example Request

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

Response

{
  "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

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

Response

{
  "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.