Skip to main content
Version: v0.6

REST API

Ory Keto is a cloud native access control server providing best-practice patterns (RBAC, ABAC, ACL, AWS IAM Policies, Kubernetes Roles, ...) via REST APIs.

info

You are viewing REST API documentation. This documentation is auto-generated from a swagger specification which itself is generated from annotations in the source code of the project. It is possible that this documentation includes bugs and that code samples are incomplete or wrong.

If you find issues in the respective documentation, please do not edit the Markdown files directly (as they are generated) but raise an issue on the project's GitHub presence instead. This documentation will improve over time with your help! If you have ideas how to improve this part of the documentation, feel free to share them in a GitHub issue any time.

read

Check a relation tuple

POST /check HTTP/1.1
Content-Type: application/json
Accept: application/json

To learn how relation tuples and the check works, head over to the documentation.

Request body

{
"namespace": "string",
"object": "string",
"relation": "string",
"subject": "string"
}

Parameters

ParameterInTypeRequiredDescription
bodybodyInternalRelationTuplefalsenone

Responses

Overview
StatusMeaningDescriptionSchema
200OKgetCheckResponsegetCheckResponse
400Bad RequestThe standard error formatInline
403ForbiddengetCheckResponsegetCheckResponse
500Internal Server ErrorThe standard error formatInline
Response Schema

Status Code 400

NameTypeRequiredRestrictionsDescription
» codeinteger(int64)falsenonenone
» details[object]falsenonenone
» messagestringfalsenonenone
» reasonstringfalsenonenone
» requeststringfalsenonenone
» statusstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
» codeinteger(int64)falsenonenone
» details[object]falsenonenone
» messagestringfalsenonenone
» reasonstringfalsenonenone
» requeststringfalsenonenone
» statusstringfalsenonenone
Examples
200 response
{
"allowed": true
}

Code samples

curl -X POST /check \
-H 'Content-Type: application/json' \ -H 'Accept: application/json'

Expand a Relation Tuple

GET /expand?namespace=string&object=string&relation=string HTTP/1.1
Accept: application/json

Use this endpoint to expand a relation tuple.

Parameters

ParameterInTypeRequiredDescription
namespacequerystringtrueNamespace of the Relation Tuple
objectquerystringtrueObject of the Relation Tuple
relationquerystringtrueRelation of the Relation Tuple
max-depthqueryinteger(int64)falsenone

Responses

Overview
StatusMeaningDescriptionSchema
200OKexpandTreeexpandTree
400Bad RequestThe standard error formatInline
404Not FoundThe standard error formatInline
500Internal Server ErrorThe standard error formatInline
Response Schema

Status Code 400

NameTypeRequiredRestrictionsDescription
» codeinteger(int64)falsenonenone
» details[object]falsenonenone
» messagestringfalsenonenone
» reasonstringfalsenonenone
» requeststringfalsenonenone
» statusstringfalsenonenone

Status Code 404

NameTypeRequiredRestrictionsDescription
» codeinteger(int64)falsenonenone
» details[object]falsenonenone
» messagestringfalsenonenone
» reasonstringfalsenonenone
» requeststringfalsenonenone
» statusstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
» codeinteger(int64)falsenonenone
» details[object]falsenonenone
» messagestringfalsenonenone
» reasonstringfalsenonenone
» requeststringfalsenonenone
» statusstringfalsenonenone
Examples
200 response
{
"children": [
{
"children": [],
"subject": "string",
"type": "union"
}
],
"subject": "string",
"type": "union"
}

Code samples

curl -X GET /expand?namespace=string&object=string&relation=string \
-H 'Accept: application/json'

Query relation tuples

GET /relation-tuples?namespace=string HTTP/1.1
Accept: application/json

Get all relation tuples that match the query. Only the namespace field is required.

Parameters

ParameterInTypeRequiredDescription
namespacequerystringtruenone
objectquerystringfalsenone
relationquerystringfalsenone
subjectquerystringfalsenone
page_tokenquerystringfalsenone
page_sizequeryinteger(int64)falsenone

Responses

Overview
StatusMeaningDescriptionSchema
200OKgetRelationTuplesResponsegetRelationTuplesResponse
404Not FoundThe standard error formatInline
500Internal Server ErrorThe standard error formatInline
Response Schema

Status Code 404

NameTypeRequiredRestrictionsDescription
» codeinteger(int64)falsenonenone
» details[object]falsenonenone
» messagestringfalsenonenone
» reasonstringfalsenonenone
» requeststringfalsenonenone
» statusstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
» codeinteger(int64)falsenonenone
» details[object]falsenonenone
» messagestringfalsenonenone
» reasonstringfalsenonenone
» requeststringfalsenonenone
» statusstringfalsenonenone
Examples
200 response
{
"next_page_token": "string",
"relation_tuples": [
{
"namespace": "string",
"object": "string",
"relation": "string",
"subject": "string"
}
]
}

Code samples

curl -X GET /relation-tuples?namespace=string \
-H 'Accept: application/json'

health

Check alive status

GET /health/alive HTTP/1.1
Accept: application/json

This endpoint returns a 200 status code when the HTTP server is up running. This status does currently not include checks whether the database connection is working.

If the service supports TLS Edge Termination, this endpoint does not require the X-Forwarded-Proto header to be set.

Be aware that if you are running multiple nodes of this service, the health status will never refer to the cluster state, only to a single instance.

Responses

Overview
StatusMeaningDescriptionSchema
200OKhealthStatushealthStatus
500Internal Server ErrorThe standard error formatInline
Response Schema

Status Code 500

NameTypeRequiredRestrictionsDescription
» codeinteger(int64)falsenonenone
» details[object]falsenonenone
» messagestringfalsenonenone
» reasonstringfalsenonenone
» requeststringfalsenonenone
» statusstringfalsenonenone
Examples
200 response
{
"status": "string"
}

Code samples

curl -X GET /health/alive \
-H 'Accept: application/json'

Check readiness status

GET /health/ready HTTP/1.1
Accept: application/json

This endpoint returns a 200 status code when the HTTP server is up running and the environment dependencies (e.g. the database) are responsive as well.

If the service supports TLS Edge Termination, this endpoint does not require the X-Forwarded-Proto header to be set.

Be aware that if you are running multiple nodes of this service, the health status will never refer to the cluster state, only to a single instance.

Responses

Overview
StatusMeaningDescriptionSchema
200OKhealthStatushealthStatus
503Service UnavailablehealthNotReadyStatushealthNotReadyStatus
Examples
200 response
{
"status": "string"
}

Code samples

curl -X GET /health/ready \
-H 'Accept: application/json'

write

Create a Relation Tuple

PUT /relation-tuples HTTP/1.1
Content-Type: application/json
Accept: application/json

Use this endpoint to create a relation tuple.

Request body

{
"namespace": "string",
"object": "string",
"relation": "string",
"subject": "string"
}

Parameters

ParameterInTypeRequiredDescription
bodybodyInternalRelationTuplefalsenone

Responses

Overview
StatusMeaningDescriptionSchema
201CreatedInternalRelationTupleInternalRelationTuple
400Bad RequestThe standard error formatInline
500Internal Server ErrorThe standard error formatInline
Response Schema

Status Code 400

NameTypeRequiredRestrictionsDescription
» codeinteger(int64)falsenonenone
» details[object]falsenonenone
» messagestringfalsenonenone
» reasonstringfalsenonenone
» requeststringfalsenonenone
» statusstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
» codeinteger(int64)falsenonenone
» details[object]falsenonenone
» messagestringfalsenonenone
» reasonstringfalsenonenone
» requeststringfalsenonenone
» statusstringfalsenonenone
Examples
201 response
{
"namespace": "string",
"object": "string",
"relation": "string",
"subject": "string"
}

Code samples

curl -X PUT /relation-tuples \
-H 'Content-Type: application/json' \ -H 'Accept: application/json'

Delete a Relation Tuple

DELETE /relation-tuples?namespace=string&object=string&relation=string HTTP/1.1
Accept: application/json

Use this endpoint to delete a relation tuple.

Parameters

ParameterInTypeRequiredDescription
namespacequerystringtrueNamespace of the Relation Tuple
objectquerystringtrueObject of the Relation Tuple
relationquerystringtrueRelation of the Relation Tuple
subjectquerystringfalseSubject of the Relation Tuple
Detailed descriptions

subject: Subject of the Relation Tuple

The subject follows the subject string encoding format.

Responses

Overview
StatusMeaningDescriptionSchema
204No ContentEmpty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is typically 201.None
400Bad RequestThe standard error formatInline
500Internal Server ErrorThe standard error formatInline
Response Schema

Status Code 400

NameTypeRequiredRestrictionsDescription
» codeinteger(int64)falsenonenone
» details[object]falsenonenone
» messagestringfalsenonenone
» reasonstringfalsenonenone
» requeststringfalsenonenone
» statusstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
» codeinteger(int64)falsenonenone
» details[object]falsenonenone
» messagestringfalsenonenone
» reasonstringfalsenonenone
» requeststringfalsenonenone
» statusstringfalsenonenone
Examples
400 response
{
"code": 0,
"details": [{}],
"message": "string",
"reason": "string",
"request": "string",
"status": "string"
}

Code samples

curl -X DELETE /relation-tuples?namespace=string&object=string&relation=string \
-H 'Accept: application/json'

Patch Multiple Relation Tuples

PATCH /relation-tuples HTTP/1.1
Content-Type: application/json
Accept: application/json

Use this endpoint to patch one or more relation tuples.

Request body

[
{
"action": "string",
"relation_tuple": {
"namespace": "string",
"object": "string",
"relation": "string",
"subject": "string"
}
}
]

Parameters

ParameterInTypeRequiredDescription
bodybodyPatchDeltafalsenone

Responses

Overview
StatusMeaningDescriptionSchema
204No ContentEmpty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is typically 201.None
400Bad RequestThe standard error formatInline
404Not FoundThe standard error formatInline
500Internal Server ErrorThe standard error formatInline
Response Schema

Status Code 400

NameTypeRequiredRestrictionsDescription
» codeinteger(int64)falsenonenone
» details[object]falsenonenone
» messagestringfalsenonenone
» reasonstringfalsenonenone
» requeststringfalsenonenone
» statusstringfalsenonenone

Status Code 404

NameTypeRequiredRestrictionsDescription
» codeinteger(int64)falsenonenone
» details[object]falsenonenone
» messagestringfalsenonenone
» reasonstringfalsenonenone
» requeststringfalsenonenone
» statusstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
» codeinteger(int64)falsenonenone
» details[object]falsenonenone
» messagestringfalsenonenone
» reasonstringfalsenonenone
» requeststringfalsenonenone
» statusstringfalsenonenone
Examples
400 response
{
"code": 0,
"details": [{}],
"message": "string",
"reason": "string",
"request": "string",
"status": "string"
}

Code samples

curl -X PATCH /relation-tuples \
-H 'Content-Type: application/json' \ -H 'Accept: application/json'

version

Get service version

GET /version HTTP/1.1
Accept: application/json

This endpoint returns the service version typically notated using semantic versioning.

If the service supports TLS Edge Termination, this endpoint does not require the X-Forwarded-Proto header to be set.

Be aware that if you are running multiple nodes of this service, the health status will never refer to the cluster state, only to a single instance.

Responses

Overview
StatusMeaningDescriptionSchema
200OKversionversion
Examples
200 response
{
"version": "string"
}

Code samples

curl -X GET /version \
-H 'Accept: application/json'

Schemas

InternalRelationTuple

{
"namespace": "string",
"object": "string",
"relation": "string",
"subject": "string"
}

Properties

NameTypeRequiredRestrictionsDescription
namespacestringtruenoneNamespace of the Relation Tuple

in: query
objectstringtruenoneObject of the Relation Tuple

in: query
relationstringtruenoneRelation of the Relation Tuple

in: query
subjectsubjecttruenonenone

PatchDelta

{
"action": "string",
"relation_tuple": {
"namespace": "string",
"object": "string",
"relation": "string",
"subject": "string"
}
}

Properties

NameTypeRequiredRestrictionsDescription
actionpatchActionfalsenonenone
relation_tupleInternalRelationTuplefalsenonenone

expandTree

{
"children": [
{
"children": [],
"subject": "string",
"type": "union"
}
],
"subject": "string",
"type": "union"
}

Properties

NameTypeRequiredRestrictionsDescription
children[expandTree]falsenonenone
subjectsubjecttruenonenone
typestringtruenonenone
Enumerated Values
PropertyValue
typeunion
typeexclusion
typeintersection
typeleaf

getCheckResponse

{
"allowed": true
}

Represents the response for a check request.

Properties

NameTypeRequiredRestrictionsDescription
allowedbooleantruenonewhether the relation tuple is allowed

getRelationTuplesResponse

{
"next_page_token": "string",
"relation_tuples": [
{
"namespace": "string",
"object": "string",
"relation": "string",
"subject": "string"
}
]
}

Properties

NameTypeRequiredRestrictionsDescription
next_page_tokenstringfalsenoneThe opaque token to provide in a subsequent request
to get the next page. It is the empty string iff this is
the last page.
relation_tuples[InternalRelationTuple]falsenonenone

healthNotReadyStatus

{
"errors": {
"property1": "string",
"property2": "string"
}
}

Properties

NameTypeRequiredRestrictionsDescription
errorsobjectfalsenoneErrors contains a list of errors that caused the not ready status.
» additionalPropertiesstringfalsenonenone

healthStatus

{
"status": "string"
}

Properties

NameTypeRequiredRestrictionsDescription
statusstringfalsenoneStatus always contains "ok".

patchAction

"string"

Properties

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

subject

"string"

Properties

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

version

{
"version": "string"
}

Properties

NameTypeRequiredRestrictionsDescription
versionstringfalsenoneVersion is the service's version.