Oso Cloud Policy API
The Policy API from Oso Cloud — 2 operation(s) for policy.
OpenAPI Specification
openapi: 3.0.3
info:
title: Oso Cloud HTTP Centralized Authorization Data Policy API
version: 0.1.0
description: 'Oso Cloud exposes an HTTP API that you can use to make queries directly, without using one of the clients.For endpoints that require authentication, pass your API key as an HTTP Bearer Auth payload.For example, using curl: curl -H "Authorization: Bearer $OSO_AUTH" https://cloud.osohq.com/api/'
servers:
- url: https://api.osohq.com/api/
tags:
- name: Policy
paths:
/policy:
get:
tags:
- Policy
description: Gets the currently active policy in Oso Cloud. The policy is expressed as a string containing [Polar](https://www.osohq.com/docs/modeling-in-polar/reference) code.
operationId: get_policy
parameters:
- name: id
in: query
schema:
type: integer
format: int64
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetPolicyResult'
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
security:
- ApiKey: []
post:
tags:
- Policy
description: Updates the policy in Oso Cloud. The policy should be represented as a string containing [Polar](https://www.osohq.com/docs/modeling-in-polar/reference) code.
operationId: post_policy
parameters:
- name: force
in: query
required: true
schema:
type: boolean
- name: show_suggestions
in: query
required: true
schema:
type: boolean
- name: fail_fast
in: query
required: true
schema:
type: boolean
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
required: true
responses:
'200':
description: The policy was updated.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResult'
'202':
description: The policy was not updated because it is unchanged.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResult'
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SavePolicyError'
security:
- ApiKey: []
x-codeSamples:
- lang: javascript
label: Node.js
source: "import { Oso } from 'oso-cloud';\n\nconst apiKey = process.env.OSO_CLOUD_API_KEY;\nconst oso = new Oso(\"https://cloud.osohq.com\", apiKey);\n\n// Update policy with Polar code\nconst policyCode = `\n actor User {}\n resource Repository {\n permissions = [\"read\", \"write\"];\n roles = [\"owner\", \"maintainer\"];\n }\n has_role(user: User, \"owner\", repo: Repository) if\n user.id = repo.owner_id;\n`;\nawait oso.policy(policyCode);\n"
- lang: python
label: Python
source: "import os\nfrom oso_cloud import Oso\n\noso = Oso(api_key=os.environ.get('OSO_CLOUD_API_KEY', None))\n\n# Update policy with Polar code\npolicy_code = \"\"\"\nactor User {}\nresource Repository {\n permissions = [\"read\", \"write\"];\n roles = [\"owner\", \"maintainer\"];\n}\nhas_role(user: User, \"owner\", repo: Repository) if\n user.id = repo.owner_id;\n\"\"\"\noso.policy(policy_code)\n"
- lang: go
label: Go
source: "package main\n\nimport (\n \"log\"\n \"os\"\n oso \"github.com/osohq/go-oso-cloud/v2\"\n)\n\nfunc main() {\n apiKey := os.Getenv(\"OSO_CLOUD_API_KEY\")\n osoClient := oso.NewClient(\"https://cloud.osohq.com\", apiKey)\n\n// Update policy with Polar code\npolicyCode := `\nactor User {}\nresource Repository {\n permissions = [\"read\", \"write\"];\n roles = [\"owner\", \"maintainer\"];\n}\nhas_role(user: User, \"owner\", repo: Repository) if\n user.id = repo.owner_id;\n`\n err := osoClient.Policy(policyCode)\n if err != nil {\n log.Fatal(err)\n }\n}\n"
- lang: java
label: Java
source: "package com.mycompany;\n\nimport java.io.IOException;\nimport com.osohq.oso_cloud.Oso;\nimport com.osohq.oso_cloud.api.ApiException;\n\npublic class App {\n public static void main(String[] args) {\n String apiKey = System.getenv(\"OSO_CLOUD_API_KEY\");\n Oso oso = new Oso(apiKey);\n\n// Update policy with Polar code\nString policyCode = \"\"\"\n actor User {}\n resource Repository {\n permissions = [\"read\", \"write\"];\n roles = [\"owner\", \"maintainer\"];\n }\n has_role(user: User, \"owner\", repo: Repository) if\n user.id = repo.owner_id;\n \"\"\";\n try {\n oso.policy(policyCode);\n } catch (IOException | ApiException e) {\n System.err.println(\"Error updating policy: \" + e.getMessage());\n }\n }\n}\n"
- lang: ruby
label: Ruby
source: "require 'oso-cloud'\n\napi_key = ENV.fetch('OSO_CLOUD_API_KEY', nil)\noso = OsoCloud::Oso.new(url: \"https://cloud.osohq.com\", api_key: api_key)\n\n# Update policy with Polar code\npolicy_code = <<~POLAR\n actor User {}\n resource Repository {\n permissions = [\"read\", \"write\"];\n roles = [\"owner\", \"maintainer\"];\n }\n has_role(user: User, \"owner\", repo: Repository) if\n user.id = repo.owner_id;\nPOLAR\noso.policy(policy_code)\n"
- lang: csharp
label: C#
source: "using OsoCloud;\n\nstring? apiKey = Environment.GetEnvironmentVariable(\"OSO_CLOUD_API_KEY\");\nvar oso = new Oso(\"https://api.osohq.com\", apiKey);\n\n// Update policy with Polar code\nvar policyCode = @\"\n actor User {}\n resource Repository {\n permissions = [\"\"read\"\", \"\"write\"\"];\n roles = [\"\"owner\"\", \"\"maintainer\"\"];\n }\n has_role(user: User, \"\"owner\"\", repo: Repository) if\n user.id = repo.owner_id;\n\";\nawait oso.Policy(policyCode);\n"
/policy_metadata:
get:
tags:
- Policy
description: Returns metadata about the currently active policy.
operationId: get_policy_metadata
parameters:
- name: id
in: query
schema:
type: integer
format: int64
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetPolicyMetadataResult'
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
security:
- ApiKey: []
x-codeSamples:
- lang: javascript
label: Node.js
source: 'import { Oso } from ''oso-cloud'';
const apiKey = process.env.OSO_CLOUD_API_KEY;
const oso = new Oso("https://cloud.osohq.com", apiKey);
// Get policy metadata
const metadata = await oso.getPolicyMetadata();
// Access resource information
console.log(metadata.resources.keys()); // List all resources
console.log(metadata.resources.get("Repository")); // Get specific resource metadata
'
- lang: python
label: Python
source: 'import os
from oso_cloud import Oso
oso = Oso(api_key=os.environ.get(''OSO_CLOUD_API_KEY'', None))
# Get policy metadata
metadata = oso.get_policy_metadata()
# Access resource information
print(metadata.resources.keys()) # List all resources
print(metadata.resources["Repository"]) # Get specific resource metadata
'
- lang: go
label: Go
source: "package main\n\nimport (\n \"log\"\n \"os\"\n oso \"github.com/osohq/go-oso-cloud/v2\"\n)\n\nfunc main() {\n apiKey := os.Getenv(\"OSO_CLOUD_API_KEY\")\n osoClient := oso.NewClient(\"https://cloud.osohq.com\", apiKey)\n\n// Get policy metadata\n metadata, err := osoClient.GetPolicyMetadata()\n if err != nil {\n log.Fatal(err)\n }\n}\n\n// Access resource information\nfor resourceName := range metadata.Resources {\n fmt.Printf(\"Resource: %s\\n\", resourceName)\n}\n"
- lang: java
label: Java
source: "package com.mycompany;\n\nimport java.io.IOException;\nimport com.osohq.oso_cloud.Oso;\nimport com.osohq.oso_cloud.api.ApiException;\n\npublic class App {\n public static void main(String[] args) {\n String apiKey = System.getenv(\"OSO_CLOUD_API_KEY\");\n Oso oso = new Oso(apiKey);\n\n // Get policy metadata\n try {\n PolicyMetadata metadata = oso.getPolicyMetadata();\n \n // Access resource information\n System.out.println(metadata.getResources().keySet());\n } catch (IOException | ApiException e) {\n System.err.println(\"Error getting policy metadata: \" + e.getMessage());\n }\n }\n}\n"
- lang: ruby
label: Ruby
source: 'require ''oso-cloud''
api_key = ENV.fetch(''OSO_CLOUD_API_KEY'', nil)
oso = OsoCloud::Oso.new(url: "https://cloud.osohq.com", api_key: api_key)
# Get policy metadata
metadata = oso.get_policy_metadata
# Access resource information
puts metadata.resources.keys
'
- lang: csharp
label: C#
source: 'using OsoCloud;
string? apiKey = Environment.GetEnvironmentVariable("OSO_CLOUD_API_KEY");
var oso = new Oso("https://api.osohq.com", apiKey);
// Get policy metadata
var metadata = await oso.GetPolicyMetadata();
// Access resource information
Console.WriteLine(string.Join(", ", metadata.Resources.Keys));
'
components:
schemas:
PolicyMetadata:
type: object
required:
- resources
properties:
resources:
type: object
additionalProperties:
$ref: '#/components/schemas/ResourceBlockData'
ApiError:
type: object
required:
- message
properties:
message:
type: string
ApiResult:
type: object
required:
- message
properties:
message:
type: string
GetPolicyResult:
type: object
properties:
policy:
allOf:
- $ref: '#/components/schemas/Policy'
nullable: true
SavePolicyError:
oneOf:
- type: object
required:
- error_type
- message
properties:
error_type:
type: string
enum:
- Generic
message:
type: string
- type: object
required:
- error_type
- errors
- message
properties:
error_type:
type: string
enum:
- Validation
message:
type: string
errors:
type: array
items:
$ref: '#/components/schemas/PolicyError'
- type: object
required:
- error_type
- message
- test_results
properties:
error_type:
type: string
enum:
- TestsFailed
message:
type: string
test_results:
$ref: '#/components/schemas/PolicyTestResult'
PolicyFailure:
description: All known failure modes for a submitted policy test. Encountering any of these scenarios means the policy test has failed.
oneOf:
- description: Polar file failed validation.
type: string
enum:
- ValidationFailed
- description: An assertion failed in an executed test.
type: string
enum:
- AssertionFailed
- description: Server hit an unexpected error.
type: string
enum:
- ServerError
ResourceBlockData:
type: object
required:
- permissions
- relations
- roles
properties:
roles:
type: array
items:
type: string
permissions:
type: array
items:
type: string
relations:
type: object
additionalProperties:
type: string
PolicyTestResult:
description: Result of a Policy test API request. Sent to `oso-cloud` CLI as JSON.
type: object
required:
- errors
- success
- tests
properties:
success:
description: Did the policy test succeed?
type: boolean
errors:
description: What errors did we encounter?
type: array
items:
$ref: '#/components/schemas/PolicyError'
tests:
description: What tests did we execute?
type: array
items:
$ref: '#/components/schemas/TestSummary'
PolicyError:
description: Error report for a failed Polar policy test, to be displayed to user. Sent to `oso-cloud` CLI as JSON.
type: object
required:
- error_type
- message
properties:
error_type:
description: Type of error encountered.
allOf:
- $ref: '#/components/schemas/PolicyFailure'
message:
description: Error message to display to the user.
type: string
Policy:
type: object
required:
- src
properties:
filename:
type: string
nullable: true
src:
type: string
GetPolicyMetadataResult:
type: object
required:
- metadata
properties:
metadata:
$ref: '#/components/schemas/PolicyMetadata'
TestSummary:
description: Results of executing a single test. Sent to `oso-cloud` CLI as JSON.
type: object
required:
- name
- passed
- total
properties:
name:
description: Name of test.
type: string
passed:
description: How many assertions passed?
type: integer
format: uint
minimum: 0
total:
description: How many assertions in total?
type: integer
format: uint
minimum: 0
securitySchemes:
ApiKey:
description: Requires an API key to access.
type: http
scheme: bearer
bearerFormat: Bearer e_0123_123_token0123