# Permissions

Permission management and access control

## GET /api/v1/permissions/definitions

> Returns (static) resource definitions of HQ's permission model.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_permissions","description":"Permission management and access control"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_PermissionDefinitions":{"type":"object","description":"Contains definitions for entities in the permission model.","properties":{"resource_definitions":{"description":"Enumerates resource definitions.","type":"array","items":{"$ref":"#/components/schemas/hq_PermissionResourceDefinition"}}},"required":["resource_definitions"]},"hq_PermissionResourceDefinition":{"type":"object","description":"Defines for each resource its format and the actions that act on it.","properties":{"service":{"description":"Has the name of the service this resource belongs to. E.g., \"kafka\".","type":"string"},"short_name":{"description":"Contains the short resource name. E.g., \"topic\".","type":"string"},"full_name":{"description":"Contains the fully qualified resource name. E.g., \"kafka:topic\".","type":"string"},"resource_format":{"description":"Is set to the resource format. E.g., \"kafka:topic:${Environment}/kafka/${Topic}\"","type":"string"},"actions":{"type":"array","description":"Enumerates the actions that operate on this resource.","items":{"type":"string"}}},"required":["service","short_name","full_name","resource_format","actions"]},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/permissions/definitions":{"get":{"description":"Returns (static) resource definitions of HQ's permission model.","operationId":"getPermissionDefinitions","responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_PermissionDefinitions"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_permissions"]}}}}
```