API Reference

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

1. Authentication

Every request must include a Bearer token in the Authorization header. Gate tokens follow the format:

vrn_gate_<environment>_<secret>

Prefix	Environment
`vrn_gate_test_`	Sandbox — safe for development and staging.
`vrn_gate_live_`	Production — access to live tenants and data.

Example header:

Authorization: Bearer vrn_gate_live_sk_9f8a7...

Tokens are scoped to a single tenant and environment and can be rotated from the Dashboard → Keys page.

2. Exchange API Key for Access Token

POST /v1/gate/tokens.exchange

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

curl -X POST https://api.vernesoft.com/v1/gate/tokens.exchange \
  -H 'Authorization: Bearer vrn_gate_test_sk_123' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "vrn_gate_test_sk_123",
    "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"
}

3. 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

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"
  }'

Response

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

4. Check Permission

POST /v1/gate/permissions.check

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/permissions.check \
  -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"
  }'

Response

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

Error Format

Gate Identity uses the same error envelope as Relay:

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

Include the request_id when contacting support for faster resolution.