> ## Documentation Index
> Fetch the complete documentation index at: https://www.osohq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Post list
> Fetches a list of resource IDs on which an actor can perform a particular action.
## OpenAPI
````yaml post /list
openapi: 3.1.0
info:
title: Oso Cloud HTTP 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/
security: []
paths:
/list:
post:
tags:
- Check API
description: >-
Fetches a list of resource IDs on which an actor can perform a
particular action. Supports pagination: provide `page_size` to receive
results in pages, with a `next_page_token` in the response for fetching
subsequent pages.
operationId: post_list
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ListQuery'
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ListResult'
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);
// List all repositories the user can read
const alice = { type: "User", id: "alice" };
const repositoryIds = await oso.list(alice, "read", "Repository");
console.log("Readable repositories:", repositoryIds);
// With context facts
const issueIds = await oso.list(
alice,
"read",
"Issue",
[
["has_relation", { type: "Issue", id: "123" }, "parent", { type: "Repository", id: "anvils" }],
["has_relation", { type: "Issue", id: "456" }, "parent", { type: "Repository", id: "acme" }]
]
);
- lang: python
label: Python
source: |
import os
from oso_cloud import Oso, Value
oso = Oso(api_key=os.environ.get('OSO_CLOUD_API_KEY', None))
# List all repositories the user can read
alice = Value("User", "alice")
repository_ids = oso.list(alice, "read", "Repository")
print(f"Readable repositories: {repository_ids}")
# With context facts
issue_ids = oso.list(
alice,
"read",
"Issue",
context_facts=[
("has_relation", Value("Issue", "123"), "parent", Value("Repository", "anvils")),
("has_relation", Value("Issue", "456"), "parent", Value("Repository", "acme"))
]
)
- lang: go
label: Go
source: >
package main
import (
"log"
"os"
oso "github.com/osohq/go-oso-cloud/v2"
)
func main() {
apiKey := os.Getenv("OSO_CLOUD_API_KEY")
osoClient := oso.NewClient("https://cloud.osohq.com", apiKey)
// List all repositories the user can read
user := oso.NewValue("User", "alice")
repositoryIds, err := osoClient.List(user, "read", "Repository",
nil)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Readable repositories: %v\n", repositoryIds)
// With context facts
contextFacts := []oso.Fact{
oso.NewFact("has_relation", oso.NewValue("Issue", "123"), oso.String("parent"), oso.NewValue("Repository", "anvils")),
oso.NewFact("has_relation", oso.NewValue("Issue", "456"), oso.String("parent"), oso.NewValue("Repository", "acme")),
}
issueIds, err := osoClient.ListWithContext(user, "read", "Issue",
contextFacts)
}
- lang: java
label: Java
source: |
package com.mycompany;
import java.io.IOException;
import java.util.Arrays;
import java.util.List;
import com.osohq.oso_cloud.Oso;
import com.osohq.oso_cloud.api.ApiException;
import com.osohq.oso_cloud.api.Value;
public class App {
public static void main(String[] args) {
String apiKey = System.getenv("OSO_CLOUD_API_KEY");
Oso oso = new Oso(apiKey);
try {
// List all repositories the user can read
Value alice = new Value("User", "alice");
List repositoryIds = oso.list(alice, "read", "Repository");
System.out.println("Readable repositories: " + repositoryIds);
// With context facts
Value issue1 = new Value("Issue", "123");
Value issue2 = new Value("Issue", "456");
Value repo1 = new Value("Repository", "anvils");
Value repo2 = new Value("Repository", "acme");
List issueIds = oso.list(alice, "read", "Issue", Arrays.asList(
Arrays.asList("has_relation", issue1, "parent", repo1),
Arrays.asList("has_relation", issue2, "parent", repo2)
));
} catch (IOException | ApiException e) {
System.err.println("Error: " + e.getMessage());
}
}
}
- 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)
# List all repositories the user can read
alice = OsoCloud::Value.new(type: "User", id: "alice")
repository_ids = oso.list(alice, "read", "Repository")
puts "Readable repositories: #{repository_ids}"
# With context facts
issue_ids = oso.list(alice, "read", "Issue",
context_facts: [
["has_relation", OsoCloud::Value.new(type: "Issue", id: "123"), "parent", OsoCloud::Value.new(type: "Repository", id: "anvils")],
["has_relation", OsoCloud::Value.new(type: "Issue", id: "456"), "parent", OsoCloud::Value.new(type: "Repository", id: "acme")]
]
)
- lang: csharp
label: C#
source: >
using OsoCloud;
string? apiKey =
Environment.GetEnvironmentVariable("OSO_CLOUD_API_KEY");
var oso = new Oso("https://api.osohq.com", apiKey);
// List all repositories the user can read
var alice = new Value("User", "alice");
var repositoryIds = await oso.List(alice, "read", "Repository");
Console.WriteLine($"Readable repositories: {string.Join(", ",
repositoryIds)}");
// With context facts
var issueIds = await oso.List(alice, "read", "Issue",
contextFacts: new[] {
new[] { "has_relation", new Value("Issue", "123"), "parent", new Value("Repository", "anvils") },
new[] { "has_relation", new Value("Issue", "456"), "parent", new Value("Repository", "acme") }
});
components:
schemas:
ListQuery:
type: object
required:
- action
- actor_id
- actor_type
- resource_type
- page_size
properties:
actor_type:
type: string
actor_id:
type: string
action:
type: string
resource_type:
type: string
context_facts:
default: []
type: array
items:
$ref: '#/components/schemas/Fact'
page_size:
description: >-
Required. Page size for pagination. Must be at least 10,000. Results
will be paginated and a `next_page_token` will be included in the
response if more results are available. Ignored when `page_token` is
provided, since the page size is determined by the original request.
default: 10000
type: integer
format: uint
minimum: 10000
page_token:
description: >-
Page token for fetching subsequent pages of results. Use the
`next_page_token` from a previous response. When provided,
`page_size` is ignored.
default: null
type: string
nullable: true
ListResult:
type: object
required:
- results
- next_page_token
properties:
results:
type: array
items:
type: string
next_page_token:
description: >-
Optional token for fetching the next page of results. Present when
more results are available.
type: string
nullable: true
ApiError:
type: object
required:
- message
properties:
message:
type: string
Fact:
description: 'A pattern object for matching authorization-relevant data, ie: facts.'
type: object
required:
- args
- predicate
properties:
predicate:
type: string
args:
type: array
items:
$ref: '#/components/schemas/Value'
Value:
type: object
properties:
type:
type: string
nullable: true
id:
type: string
nullable: true
securitySchemes:
ApiKey:
description: Requires an API key to access.
type: http
scheme: bearer
bearerFormat: Bearer e_0123_123_token0123
````