Version: v0.5

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.

engines#

Check If a Request is Allowed#

POST /engines/acp/ory/{flavor}/allowed HTTP/1.1
Content-Type: application/json
Accept: application/json

Use this endpoint to check if a request is allowed or not. If the request is allowed, a 200 response with {"allowed":"true"} will be sent. If the request is denied, a 403 response with {"allowed":"false"} will be sent instead.

Request body#

{
"action": "string",
"context": {},
"resource": "string",
"subject": "string"
}

Parameters#

ParameterInTypeRequiredDescription
flavorpathstringtrueThe ORY Access Control Policy flavor. Can be "regex", "glob", and "exact".
bodybodyoryAccessControlPolicyAllowedInputfalsenone

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKauthorizationResultauthorizationResult
403ForbiddenauthorizationResultauthorizationResult
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#
{
"allowed": true
}

Code samples#

curl -X POST /engines/acp/ory/{flavor}/allowed \
-H 'Content-Type: application/json' \ -H 'Accept: application/json'

listOryAccessControlPolicies#

GET /engines/acp/ory/{flavor}/policies HTTP/1.1
Accept: application/json

List ORY Access Control Policies

Parameters#

ParameterInTypeRequiredDescription
flavorpathstringtrueThe ORY Access Control Policy flavor. Can be "regex", "glob", and "exact"
limitqueryinteger(int64)falseThe maximum amount of policies returned.
offsetqueryinteger(int64)falseThe offset from where to start looking.
subjectquerystringfalseThe subject for whom the policies are to be listed.
resourcequerystringfalseThe resource for which the policies are to be listed.
actionquerystringfalseThe action for which policies are to be listed.

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKPolicies is an array of policies.Inline
500Internal Server ErrorThe standard error formatInline
Response Schema#

Status Code 200

NameTypeRequiredRestrictionsDescription
anonymous[oryAccessControlPolicy]falsenonenone
ยป oryAccessControlPolicy specifies an ORY Access Policy document.oryAccessControlPolicyfalsenonenone
ยปยป actions[string]falsenoneActions is an array representing all the actions this ORY Access Policy applies to.
ยปยป conditionsobjectfalsenoneConditions represents a keyed object of conditions under which this ORY Access Policy is active.
ยปยป descriptionstringfalsenoneDescription is an optional, human-readable description.
ยปยป effectstringfalsenoneEffect is the effect of this ORY Access Policy. It can be "allow" or "deny".
ยปยป idstringfalsenoneID is the unique identifier of the ORY Access Policy. It is used to query, update, and remove the ORY Access Policy.
ยปยป resources[string]falsenoneResources is an array representing all the resources this ORY Access Policy applies to.
ยปยป subjects[string]falsenoneSubjects is an array representing all the subjects this ORY Access Policy applies to.

Status Code 500

NameTypeRequiredRestrictionsDescription
ยป codeinteger(int64)falsenonenone
ยป details[object]falsenonenone
ยป messagestringfalsenonenone
ยป reasonstringfalsenonenone
ยป requeststringfalsenonenone
ยป statusstringfalsenonenone
Examples#
200 response#
[
{
"actions": [
"string"
],
"conditions": {},
"description": "string",
"effect": "string",
"id": "string",
"resources": [
"string"
],
"subjects": [
"string"
]
}
]

Code samples#

curl -X GET /engines/acp/ory/{flavor}/policies \
-H 'Accept: application/json'

upsertOryAccessControlPolicy#

PUT /engines/acp/ory/{flavor}/policies HTTP/1.1
Content-Type: application/json
Accept: application/json

Upsert an ORY Access Control Policy

Request body#

{
"actions": [
"string"
],
"conditions": {},
"description": "string",
"effect": "string",
"id": "string",
"resources": [
"string"
],
"subjects": [
"string"
]
}

Parameters#

ParameterInTypeRequiredDescription
flavorpathstringtrueThe ORY Access Control Policy flavor. Can be "regex", "glob", and "exact".
bodybodyoryAccessControlPolicyfalsenone

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKoryAccessControlPolicyoryAccessControlPolicy
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#
{
"actions": [
"string"
],
"conditions": {},
"description": "string",
"effect": "string",
"id": "string",
"resources": [
"string"
],
"subjects": [
"string"
]
}

Code samples#

curl -X PUT /engines/acp/ory/{flavor}/policies \
-H 'Content-Type: application/json' \ -H 'Accept: application/json'

getOryAccessControlPolicy#

GET /engines/acp/ory/{flavor}/policies/{id} HTTP/1.1
Accept: application/json

Get an ORY Access Control Policy

Parameters#

ParameterInTypeRequiredDescription
flavorpathstringtrueThe ORY Access Control Policy flavor. Can be "regex", "glob", and "exact".
idpathstringtrueThe ID of the ORY Access Control Policy Role.

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKoryAccessControlPolicyoryAccessControlPolicy
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#
{
"actions": [
"string"
],
"conditions": {},
"description": "string",
"effect": "string",
"id": "string",
"resources": [
"string"
],
"subjects": [
"string"
]
}

Code samples#

curl -X GET /engines/acp/ory/{flavor}/policies/{id} \
-H 'Accept: application/json'

deleteOryAccessControlPolicy#

DELETE /engines/acp/ory/{flavor}/policies/{id} HTTP/1.1
Accept: application/json

Delete an ORY Access Control Policy

Parameters#

ParameterInTypeRequiredDescription
flavorpathstringtrueThe ORY Access Control Policy flavor. Can be "regex", "glob", and "exact".
idpathstringtrueThe ID of the ORY Access Control Policy Role.

Responses#

Overview#
StatusMeaningDescriptionSchema
204No ContentAn empty responseNone
500Internal Server ErrorThe standard error formatInline
Response Schema#

Status Code 500

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

Code samples#

curl -X DELETE /engines/acp/ory/{flavor}/policies/{id} \
-H 'Accept: application/json'

List ORY Access Control Policy Roles#

GET /engines/acp/ory/{flavor}/roles HTTP/1.1
Accept: application/json

Roles group several subjects into one. Rules can be assigned to ORY Access Control Policy (OACP) by using the Role ID as subject in the OACP.

Parameters#

ParameterInTypeRequiredDescription
flavorpathstringtrueThe ORY Access Control Policy flavor. Can be "regex", "glob", and "exact"
limitqueryinteger(int64)falseThe maximum amount of policies returned.
offsetqueryinteger(int64)falseThe offset from where to start looking.
memberquerystringfalseThe member for which the roles are to be listed.

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKRoles is an array of roles.Inline
500Internal Server ErrorThe standard error formatInline
Response Schema#

Status Code 200

NameTypeRequiredRestrictionsDescription
anonymous[oryAccessControlPolicyRole]falsenone[oryAccessControlPolicyRole represents a group of users that share the same role. A role could be an administrator, a moderator, a regular user or some other sort of role.]
ยป descriptionstringfalsenoneDescription is the description of the role.
ยป idstringfalsenoneID is the role's unique id.
ยป members[string]falsenoneMembers is who belongs to the role.

Status Code 500

NameTypeRequiredRestrictionsDescription
ยป codeinteger(int64)falsenonenone
ยป details[object]falsenonenone
ยป messagestringfalsenonenone
ยป reasonstringfalsenonenone
ยป requeststringfalsenonenone
ยป statusstringfalsenonenone
Examples#
200 response#
[
{
"description": "string",
"id": "string",
"members": [
"string"
]
}
]

Code samples#

curl -X GET /engines/acp/ory/{flavor}/roles \
-H 'Accept: application/json'

Upsert an ORY Access Control Policy Role#

PUT /engines/acp/ory/{flavor}/roles HTTP/1.1
Content-Type: application/json
Accept: application/json

Roles group several subjects into one. Rules can be assigned to ORY Access Control Policy (OACP) by using the Role ID as subject in the OACP.

Request body#

{
"description": "string",
"id": "string",
"members": [
"string"
]
}

Parameters#

ParameterInTypeRequiredDescription
flavorpathstringtrueThe ORY Access Control Policy flavor. Can be "regex", "glob", and "exact".
bodybodyoryAccessControlPolicyRolefalsenone

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKoryAccessControlPolicyRoleoryAccessControlPolicyRole
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#
{
"description": "string",
"id": "string",
"members": [
"string"
]
}

Code samples#

curl -X PUT /engines/acp/ory/{flavor}/roles \
-H 'Content-Type: application/json' \ -H 'Accept: application/json'

Get an ORY Access Control Policy Role#

GET /engines/acp/ory/{flavor}/roles/{id} HTTP/1.1
Accept: application/json

Roles group several subjects into one. Rules can be assigned to ORY Access Control Policy (OACP) by using the Role ID as subject in the OACP.

Parameters#

ParameterInTypeRequiredDescription
flavorpathstringtrueThe ORY Access Control Policy flavor. Can be "regex", "glob", and "exact".
idpathstringtrueThe ID of the ORY Access Control Policy Role.

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKoryAccessControlPolicyRoleoryAccessControlPolicyRole
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#
{
"description": "string",
"id": "string",
"members": [
"string"
]
}

Code samples#

curl -X GET /engines/acp/ory/{flavor}/roles/{id} \
-H 'Accept: application/json'

Delete an ORY Access Control Policy Role#

DELETE /engines/acp/ory/{flavor}/roles/{id} HTTP/1.1
Accept: application/json

Roles group several subjects into one. Rules can be assigned to ORY Access Control Policy (OACP) by using the Role ID as subject in the OACP.

Parameters#

ParameterInTypeRequiredDescription
flavorpathstringtrueThe ORY Access Control Policy flavor. Can be "regex", "glob", and "exact".
idpathstringtrueThe ID of the ORY Access Control Policy Role.

Responses#

Overview#
StatusMeaningDescriptionSchema
204No ContentAn empty responseNone
500Internal Server ErrorThe standard error formatInline
Response Schema#

Status Code 500

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

Code samples#

curl -X DELETE /engines/acp/ory/{flavor}/roles/{id} \
-H 'Accept: application/json'

Add a Member to an ORY Access Control Policy Role#

PUT /engines/acp/ory/{flavor}/roles/{id}/members HTTP/1.1
Content-Type: application/json
Accept: application/json

Roles group several subjects into one. Rules can be assigned to ORY Access Control Policy (OACP) by using the Role ID as subject in the OACP.

Request body#

{
"members": [
"string"
]
}

Parameters#

ParameterInTypeRequiredDescription
flavorpathstringtrueThe ORY Access Control Policy flavor. Can be "regex", "glob", and "exact".
idpathstringtrueThe ID of the ORY Access Control Policy Role.
bodybodyaddOryAccessControlPolicyRoleMembersBodyfalsenone

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKoryAccessControlPolicyRoleoryAccessControlPolicyRole
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#
{
"description": "string",
"id": "string",
"members": [
"string"
]
}

Code samples#

curl -X PUT /engines/acp/ory/{flavor}/roles/{id}/members \
-H 'Content-Type: application/json' \ -H 'Accept: application/json'

Remove a Member From an ORY Access Control Policy Role#

DELETE /engines/acp/ory/{flavor}/roles/{id}/members/{member} HTTP/1.1
Accept: application/json

Roles group several subjects into one. Rules can be assigned to ORY Access Control Policy (OACP) by using the Role ID as subject in the OACP.

Parameters#

ParameterInTypeRequiredDescription
flavorpathstringtrueThe ORY Access Control Policy flavor. Can be "regex", "glob", and "exact".
idpathstringtrueThe ID of the ORY Access Control Policy Role.
memberpathstringtrueThe member to be removed.

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKAn empty responseNone
500Internal Server ErrorThe standard error formatInline
Response Schema#

Status Code 500

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

Code samples#

curl -X DELETE /engines/acp/ory/{flavor}/roles/{id}/members/{member} \
-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'

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#

addOryAccessControlPolicyRoleMembersBody#

{
"members": [
"string"
]
}

Properties#

NameTypeRequiredRestrictionsDescription
members[string]falsenoneThe members to be added.

authorizationResult#

{
"allowed": true
}

AuthorizationResult is the result of an access control decision. It contains the decision outcome.

Properties#

NameTypeRequiredRestrictionsDescription
allowedbooleantruenoneAllowed is true if the request should be allowed and false otherwise.

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".

oryAccessControlPolicy#

{
"actions": [
"string"
],
"conditions": {},
"description": "string",
"effect": "string",
"id": "string",
"resources": [
"string"
],
"subjects": [
"string"
]
}

oryAccessControlPolicy specifies an ORY Access Policy document.

Properties#

NameTypeRequiredRestrictionsDescription
actions[string]falsenoneActions is an array representing all the actions this ORY Access Policy applies to.
conditionsobjectfalsenoneConditions represents a keyed object of conditions under which this ORY Access Policy is active.
descriptionstringfalsenoneDescription is an optional, human-readable description.
effectstringfalsenoneEffect is the effect of this ORY Access Policy. It can be "allow" or "deny".
idstringfalsenoneID is the unique identifier of the ORY Access Policy. It is used to query, update, and remove the ORY Access Policy.
resources[string]falsenoneResources is an array representing all the resources this ORY Access Policy applies to.
subjects[string]falsenoneSubjects is an array representing all the subjects this ORY Access Policy applies to.

oryAccessControlPolicyAllowedInput#

{
"action": "string",
"context": {},
"resource": "string",
"subject": "string"
}

Input for checking if a request is allowed or not.

Properties#

NameTypeRequiredRestrictionsDescription
actionstringfalsenoneAction is the action that is requested on the resource.
contextobjectfalsenoneContext is the request's environmental context.
resourcestringfalsenoneResource is the resource that access is requested to.
subjectstringfalsenoneSubject is the subject that is requesting access.

oryAccessControlPolicyRole#

{
"description": "string",
"id": "string",
"members": [
"string"
]
}

oryAccessControlPolicyRole represents a group of users that share the same role. A role could be an administrator, a moderator, a regular user or some other sort of role.

Properties#

NameTypeRequiredRestrictionsDescription
descriptionstringfalsenoneDescription is the description of the role.
idstringfalsenoneID is the role's unique id.
members[string]falsenoneMembers is who belongs to the role.

version#

{
"version": "string"
}

Properties#

NameTypeRequiredRestrictionsDescription
versionstringfalsenoneVersion is the service's version.
Last updated on by aeneasr