{"id": "authentication:createtokenview", "page": "authentication", "ref": "createtokenview", "title": "API Tokens", "content": "Datasette includes a default mechanism for generating API tokens that can be used to authenticate requests. \n             Authenticated users can create new API tokens using a form on the  /-/create-token  page. \n             Tokens created in this way can be further restricted to only allow access to specific actions, or to limit those actions to specific databases, tables or queries. \n             Created tokens can then be passed in the  Authorization: Bearer $token  header of HTTP requests to Datasette. \n             A token created by a user will include that user's  \"id\"  in the token payload, so any permissions granted to that user based on their ID can be made available to the token as well. \n             When one of these a token accompanies a request, the actor for that request will have the following shape: \n             {\n    \"id\": \"user_id\",\n    \"token\": \"dstok\",\n    \"token_expires\": 1667717426\n} \n             The  \"id\"  field duplicates the ID of the actor who first created the token. \n             The  \"token\"  field identifies that this actor was authenticated using a Datasette signed token ( dstok ). \n             The  \"token_expires\"  field, if present, indicates that the token will expire after that integer timestamp. \n             The  /-/create-token  page cannot be accessed by actors that are authenticated with a  \"token\": \"some-value\"  property. This is to prevent API tokens from being used to create more tokens. \n             Datasette plugins that implement their own form of API token authentication should follow this convention. \n             You can disable the signed token feature entirely using the  allow_signed_tokens  setting.", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}
{"id": "authentication:authentication-permissions-config", "page": "authentication", "ref": "authentication-permissions-config", "title": "Access permissions in ", "content": "There are two ways to configure permissions using  datasette.yaml  (or  datasette.json ). \n             For simple visibility permissions you can use  \"allow\"  blocks in the root, database, table and query sections. \n             For other permissions you can use a  \"permissions\"  block, described  in the next section . \n             You can limit who is allowed to view different parts of your Datasette instance using  \"allow\"  keys in your  Configuration . \n             You can control the following: \n             \n                 \n                     Access to the entire Datasette instance \n                 \n                 \n                     Access to specific databases \n                 \n                 \n                     Access to specific tables and views \n                 \n                 \n                     Access to specific  Canned queries \n                 \n             \n             If a user cannot access a specific database, they will not be able to access tables, views or queries within that database. If a user cannot access the instance they will not be able to access any of the databases, tables, views or queries.", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}
{"id": "authentication:authentication-actor", "page": "authentication", "ref": "authentication-actor", "title": "Actors", "content": "Through plugins, Datasette can support both authenticated users (with cookies) and authenticated API agents (via authentication tokens). The word \"actor\" is used to cover both of these cases. \n             Every request to Datasette has an associated actor value, available in the code as  request.actor . This can be  None  for unauthenticated requests, or a JSON compatible Python dictionary for authenticated users or API agents. \n             The actor dictionary can be any shape - the design of that data structure is left up to the plugins. A useful convention is to include an  \"id\"  string, as demonstrated by the \"root\" actor below. \n             Plugins can use the  actor_from_request(datasette, request)  hook to implement custom logic for authenticating an actor based on the incoming HTTP request.", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}
{"id": "authentication:id1", "page": "authentication", "ref": "id1", "title": "Built-in permissions", "content": "This section lists all of the permission checks that are carried out by Datasette core, along with the  resource  if it was passed.", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}
{"id": "authentication:permissions-plugins", "page": "authentication", "ref": "permissions-plugins", "title": "Checking permissions in plugins", "content": "Datasette plugins can check if an actor has permission to perform an action using the  datasette.permission_allowed(...)  method. \n             Datasette core performs a number of permission checks,  documented below . Plugins can implement the  permission_allowed(datasette, actor, action, resource)  plugin hook to participate in decisions about whether an actor should be able to perform a specified action.", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}
{"id": "authentication:authentication-permissions-other", "page": "authentication", "ref": "authentication-permissions-other", "title": "Other permissions in ", "content": "For all other permissions, you can use one or more  \"permissions\"  blocks in your  datasette.yaml  configuration file. \n             To grant access to the  permissions debug tool  to all signed in users, you can grant  permissions-debug  to any actor with an  id  matching the wildcard  *  by adding this a the root of your configuration: \n             [[[cog\nconfig_example(cog, \"\"\"\n    permissions:\n      debug-menu:\n        id: '*'\n\"\"\") \n             ]]] \n             [[[end]]] \n             To grant  create-table  to the user with  id  of  editor  for the  docs  database: \n             [[[cog\nconfig_example(cog, \"\"\"\n    databases:\n      docs:\n        permissions:\n          create-table:\n            id: editor\n\"\"\") \n             ]]] \n             [[[end]]] \n             And for  insert-row  against the  reports  table in that  docs  database: \n             [[[cog\nconfig_example(cog, \"\"\"\n    databases:\n      docs:\n        tables:\n          reports:\n            permissions:\n              insert-row:\n                id: editor\n\"\"\") \n             ]]] \n             [[[end]]] \n             The  permissions debug tool  can be useful for helping test permissions that you have configured in this way.", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}
{"id": "authentication:authentication-permissions", "page": "authentication", "ref": "authentication-permissions", "title": "Permissions", "content": "Datasette has an extensive permissions system built-in, which can be further extended and customized by plugins. \n             The key question the permissions system answers is this: \n             \n                 Is this  actor  allowed to perform this  action , optionally against this particular  resource ? \n             \n             Actors  are  described above . \n             An  action  is a string describing the action the actor would like to perform. A full list is  provided below  - examples include  view-table  and  execute-sql . \n             A  resource  is the item the actor wishes to interact with - for example a specific database or table. Some actions, such as  permissions-debug , are not associated with a particular resource. \n             Datasette's built-in view permissions ( view-database ,  view-table  etc) default to  allow  - unless you  configure additional permission rules  unauthenticated users will be allowed to access content. \n             Permissions with potentially harmful effects should default to  deny . Plugin authors should account for this when designing new plugins - for example, the  datasette-upload-csvs  plugin defaults to deny so that installations don't accidentally allow unauthenticated users to create new tables by uploading a CSV file.", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette-upload-csvs\", \"label\": \"datasette-upload-csvs\"}]"}
{"id": "authentication:authentication-ds-actor", "page": "authentication", "ref": "authentication-ds-actor", "title": "The ds_actor cookie", "content": "Datasette includes a default authentication plugin which looks for a signed  ds_actor  cookie containing a JSON actor dictionary. This is how the  root actor  mechanism works. \n             Authentication plugins can set signed  ds_actor  cookies themselves like so: \n             response = Response.redirect(\"/\")\nresponse.set_cookie(\n    \"ds_actor\",\n    datasette.sign({\"a\": {\"id\": \"cleopaws\"}}, \"actor\"),\n) \n             Note that you need to pass  \"actor\"  as the namespace to  .sign(value, namespace=\"default\") . \n             The shape of data encoded in the cookie is as follows: \n             {\n    \"a\": {... actor ...}\n}", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}
{"id": "authentication:permissionsdebugview", "page": "authentication", "ref": "permissionsdebugview", "title": "The permissions debug tool", "content": "The debug tool at  /-/permissions  is only available to the  authenticated root user  (or any actor granted the  permissions-debug  action). \n             It shows the thirty most recent permission checks that have been carried out by the Datasette instance. \n             It also provides an interface for running hypothetical permission checks against a hypothetical actor. This is a useful way of confirming that your configured permissions work in the way you expect. \n             This is designed to help administrators and plugin authors understand exactly how permission checks are being carried out, in order to effectively configure Datasette's permission system.", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}
{"id": "authentication:authentication-actor-matches-allow", "page": "authentication", "ref": "authentication-actor-matches-allow", "title": "actor_matches_allow()", "content": "Plugins that wish to implement this same  \"allow\"  block permissions scheme can take advantage of the  datasette.utils.actor_matches_allow(actor, allow)  function: \n             from datasette.utils import actor_matches_allow\n\nactor_matches_allow({\"id\": \"root\"}, {\"id\": \"*\"})\n# returns True \n             The currently authenticated actor is made available to plugins as  request.actor .", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}