List Resources

Lists resources within an organization account.

If a kind query parameter is given, narrows results to only resources of that kind.

If a limit is given, returns no more than that number of results. Providing an offset skips a number of resources before returning the rest. In addition, providing an offset will give limit a default value of 10 if none other is provided. These two parameters can be combined to page through results.

If the parameter count is true, returns only the number of items in the list.

If the role or acting_as query parameter is given, then the resource list can be retrieved for a different role (as long as the authenticated role has access).

Text search

If the search parameter is provided, narrows results to those pertaining to the search query. Search works across resource IDs and the values of annotations. It weights results so that those with matching id or a matching value of an annotation called name appear first, then those with another matching annotation value, and finally those with a matching kind.

Kinds of resources

Kind

Description

User

one unique human

Host

a single logical machine (in the broad sense, not just physical)

Layer

a collection of hosts that have the same privileges

Group

a collection of users and groups that have the same privileges

Policy

privileges on policies enable a user to create and modify objects and permissions

Variable

a secret such as a password, API key, SSH key, etc

Webservice

an HTTP(S) web service which performs sensitive operations

URI

 
GET /resources/{account}{?kind}{?search}{?limit}{?offset}{?count}{?acting_as}

Example with curl and jq

Suppose your organization name is “myorg” and you want to search for the first two resources matching the word “db”:

 
curl -H "$(conjur authn authenticate -H)" \
     'https://eval.conjur.org/resources/myorg?search=db&limit=2' \
     | jq .

Request Headers

Field

Description

Example

Authorization

Conjur access token

Token token=“eyJkYX…Rhb=”

Response

Code

Description

200

Resources returned as a JSON list

401

The request lacks valid authentication credentials

403

The authenticated user lacks the necessary privilege

Example URI

 
GET /resources/myorg?kind=variable?search=password?limit=2?offset=6?count=false

URI Parameters

Parameter

Type

Mandatory

Description

account

String

Yes

Organization account name

Example: myorg

kind

String

No

kind of object to list

Example: variable

search

String

No

search term used to narrow results

Example: password

limit

number

No

maximum number of results to return

Example: 2

offset

number

No

number of results to skip

Example: 6

count

boolean

No

if true, return only the number of items in the list

Example: false

acting_as

String

No

The fully qualified identifier for the role whose resource list you want to view. It should be entered as {account}:{kind}:{identifier} where the identifier is URL-encoded. For more information about URL encoding, see URI.

Example: cucumber:user:alice

Request

Headers

 
Authorization: Token token="eyJkYX...Rhb="

Response 200

Headers

 
Content-Type: application/json

Body

 
[
  {
    "created_at": "2017-07-25T06:30:38.768+00:00",
    "id": "myorg:variable:app-prod/db-password",
    "owner": "myorg:policy:app-prod",
    "policy": "myorg:policy:root",
    "permissions": [],
    "annotations": [],
    "secrets": [
      {
        "version": 1
      }
    ]
  },
  {
    "created_at": "2017-07-25T06:30:38.768+00:00",
    "id": "myorg:policy:app-prod",
    "owner": "myorg:user:admin",
    "policy": "myorg:policy:root",
    "permissions": [],
    "annotations": [],
    "policy_versions": []
  }
]