Skip to main content
Version: Next

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.
Last updated on by hackerman