Skip to main content

Quick Start

From zero to a working access check. Set up your model in the dashboard or with Terraform, then call it from your code or a local agent.

Dashboard flow​

1. Sign in​

Go to console.vengtoo.com and sign in.

2. Define a resource type​

Schema → Resource Types → New Type. A resource type describes a category of thing you protect and the actions available on it.

Example:

  • Name: document
  • Actions: read, write, delete, share

3. Create a resource​

Resources → Create Resource.

Example:

  • Name: Engineering Wiki
  • Type: document

New resources land in your default namespace. To keep resources separate, create a namespace and select it here — optional, and you can do it later.

Production tip: Set the External ID field to your system's own identifier for this resource (e.g., your database UUID). You can then pass it as resource.external_id in evaluation calls instead of looking up Vengtoo's internal ID.

4. Add a subject​

Subjects → Create Subject.

Example:

  • Name: Alice
  • Type: user

Production tip: Set the External ID field to your system's user ID — the UUID from your user table or whatever your auth token carries. Your backend always has this value; you won't need a separate lookup at evaluation time.

5. Create a policy​

Policies → Create Policy:

  • Name: alice-can-read-write
  • Effect: ALLOW
  • Actions: read, write
  • Resource type: document

Assign the policy directly to Alice. (For team-wide access, assign it to a role and give people that role instead — see Access Paths.)

6. Get credentials​

Now you need a credential to call the API. Create an API key under Profile → Settings → API access → API Keys → Create API Key — it starts with azx_ and is the simplest way to start.

Prefer short-lived, scoped tokens? Vengtoo also supports OAuth2 client credentials — standards-compliant and better for compliance-sensitive setups. See OAuth Client Credentials.

7. Make your first API call​

You can identify a subject or resource in three ways — use whichever matches what your backend already knows:

IdentifierWhen to use
idYou have Vengtoo's internal UUID (e.g., stored after creation)
external_idRecommended for production. Your own stable ID (database UUID, auth token sub). Enforced unique per tenant.
type + nameHandy for demos and scripts. Names are not enforced unique, so avoid this in production code.
curl -X POST https://api.vengtoo.com/access/v1/evaluation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject":  { "id": "ALICE_SUBJECT_ID", "type": "user" },
    "resource": { "type": "document", "name": "Engineering Wiki" },
    "action":   { "name": "read" }
  }'

Response:

{
  "decision": true,
  "context": {
    "reason": "Policy 'alice-can-read-write' grants access",
    "policy_id": "...",
    "access_path": "direct"
  }
}

Switch action to {"name": "delete"} and the same call returns "decision": false.

Prefer Terraform? Set it up as code​

This is an alternative to the dashboard flow above — not an extra step. If you already created your resource and policy in the dashboard, you're done; skip to Run evaluations locally. If you'd rather manage your authorization model in version control, do it here instead.

The Terraform provider authenticates via OAuth Client Credentials, so create an OAuth client first (step 6).

export VENGTOO_CLIENT_ID=client_...
export VENGTOO_CLIENT_SECRET=azx_cs_...
terraform {
  required_providers {
    vengtoo = { source = "vengtoo/vengtoo", version = "~> 1.0" }
  }
}

provider "vengtoo" {}

resource "vengtoo_resource_type" "document" {
  name    = "document"
  actions = ["read", "write", "delete", "share"]
}

resource "vengtoo_resource" "wiki" {
  name = "Engineering Wiki"
  type = vengtoo_resource_type.document.id
}

resource "vengtoo_subject" "alice" {
  name = "Alice"
  type = "user"
}

resource "vengtoo_policy" "alice_can_edit" {
  name     = "alice-can-read-write"
  effect   = "ALLOW"
  priority = 50
  resources = [{
    resource_id = vengtoo_resource.wiki.id
    actions     = ["read", "write"]
  }]
}

resource "vengtoo_policy_assignment" "alice_policy" {
  policy_id   = vengtoo_policy.alice_can_edit.id
  entity_type = "subject"
  entity_id   = vengtoo_subject.alice.id
}
terraform init && terraform apply

Now run a check exactly like step 7 above — your policy is live.

Full reference: Terraform Provider.

Run evaluations locally​

Run decisions next to your service with the Vengtoo Agent — sub-millisecond, and it keeps serving from a cached bundle when the cloud is unreachable. Same request shape as the cloud.

Image: vengtoo/agent on Docker Hub.

docker run -d \
  -e VENGTOO_API_KEY=azx_... \
  -p 8181:8181 \
  -v vengtoo-cache:/var/lib/vengtoo/bundles \
  vengtoo/agent:latest

Then run the same check as step 7, pointed at the agent on localhost:8181. No API key is needed on calls to the agent — it authenticates with the cloud on your behalf to fetch your policy bundle.

curl -X POST http://localhost:8181/access/v1/evaluation \
  -H "Content-Type: application/json" \
  -d '{
    "subject":  { "id": "ALICE_SUBJECT_ID", "type": "user" },
    "resource": { "type": "document", "name": "Engineering Wiki" },
    "action":   { "name": "read" }
  }'

You get the same decision response — evaluated locally in sub-millisecond time.

Full agent config (metrics, decision logs, graceful degradation): Vengtoo Agent.

Integrate with an SDK​

Vengtoo provides official SDKs, currently for Go, Node, and Python — each pointed at Vengtoo Cloud or a local agent. Prefer another language? Call the HTTP API directly, like step 7, until we ship an SDK for it.

go get github.com/vengtoo/vengtoo-go
client := vengtoo.NewClient("YOUR_API_KEY")
decision, _ := client.Check(ctx,
  vengtoo.Subject{ExternalID: "alice-uuid-from-your-db", Type: "user"},
  "read",
  vengtoo.Resource{ExternalID: "wiki-uuid-from-your-db", Type: "document"},
)

To send checks to a local agent instead of the cloud, point the SDK at it — same call:

client := vengtoo.NewClient("YOUR_API_KEY", vengtoo.WithBaseURL("http://localhost:8181"))

What's next​