Reference
/
Client APIs
/
Go

Go Client API

💡

Before going through this guide, make sure you follow the Oso Cloud Quickstart to get your Oso API Key properly set in your environment.

First, install the go-oso-cloud package:

go get github.com/osohq/go-oso-cloud

Instantiating an Oso Cloud Client

The Oso Cloud library works by providing an Oso class which you configure with your Oso Cloud URL:

import (
  ...

  oso "github.com/osohq/go-oso-cloud"
)

osoClient := oso.NewClient("https://cloud.osohq.com", YOUR_API_KEY)

// Later:
e := osoClient.Tell("has_role", user, role, resource)
if e != nil {
	// Handle error.
}

// Wherever authorization needs to be performed:
allowed, e := osoClient.Authorize(user, action, resource)
if e != nil {
	// Handle error.
}

if allowed {
	// Action is allowed.
}

Write API

💡

Under the hood, Oso represents your objects as a TYPE and an ID. Right now, the Go API requires that objects passed to these methods have Type() and Id() getters, which together form a unique type/ID combination.

Add fact: osoClient.Tell(predicate[, arg0[, arg1[, ...]]])

Adds a fact named predicate with the provided arguments. Example:

osoClient.Tell("has_role", User{id: "bob"}, oso.String("owner"), Organization{id: "acme"})

Add many facts: osoClient.BulkTell([]oso.BulkFact)

Adds many facts at once. Example:

osoClient.BulkTell([]oso.BulkFact{
  oso.BulkFact{
    Predicate: "has_role",
    Args: []oso.Instance{User{id: "bob"}, oso.String("owner"), Organization{id: "acme"}},
  },
  oso.BulkFact{
    Predicate: "has_role",
    Args: []oso.Instance{User{id: "bob"}, oso.String("maintainer"), Repository{id: "anvil"}},
  },
})

Delete fact: osoClient.Delete(predicate[, arg0[, arg1[, ...]]])

Deletes a fact. Does not throw an error if the fact is not found. Example:

e := osoClient.Delete("has_role", User{id: "bob"}, oso.String("maintainer"), Repository{id: "anvil"})

Delete many facts: osoClient.BulkDelete([]oso.BulkFact)

Deletes many facts at once. Does not throw an error when some of the facts are not found. Example:

osoClient.BulkDelete([]oso.BulkFact{
  oso.BulkFact{
    Predicate: "has_role",
    Args: []oso.Instance{User{id: "bob"}, oso.String("owner"), Organization{id: "acme"}},
  },
  oso.BulkFact{
    Predicate: "has_role",
    Args: []oso.Instance{User{id: "bob"}, oso.String("maintainer"), Repository{id: "anvil"}},
  },
})

Check API

💡

Under the hood, Oso represents your objects as a TYPE and an ID. Right now, the Go API requires that objects passed to these methods have Type() and Id() getters, which together form a unique type/ID combination.

Check a permission: osoClient.Authorize(actor, action, resource)

Determines whether or not an action is allowed, based on a combination of authorization data and policy logic. Example:

allowed, e := osoClient.Authorize(user, "read", anvilsRepository)
if e != nil {
	// Handle error.
}
if allowed {
	// Action is allowed.
}

Check authorized resources: osoClient.AuthorizeResources(actor, action, resources)

Returns a subset of resources on which an actor can perform a particular action. Ordering and duplicates, if any exist, are preserved. Example:

results, e := osoClient.AuthorizeResources(user, "read", []Instance{anvilsRepository, acmeRepository})

List authorized resources: osoClient.List(actor, action, resourceType)

Fetches a list of resources on which an actor can perform a particular action. Example:

repositoryIds, e := osoClient.List(user, "read", Repository{})

List authorized actions: osoClient.Actions(actor, resource)

Fetches a list of actions which an actor can perform on a particular resource. Example:

actions, e := osoClient.Actions(user, anvilsRepository)

Talk to an Oso Engineer

Our team is happy to help you get started with Oso. If you'd like to learn more about using Oso in your app or have any questions about this guide, schedule a 1x1 with an Oso engineer.

Get started with Oso Cloud →

Last updated on May 26, 2022