{"ok": true, "next": null, "rows": [{"id": "authentication:actions", "page": "authentication", "ref": "actions", "title": "Built-in actions", "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:actions-alter-table", "page": "authentication", "ref": "actions-alter-table", "title": "alter-table", "content": "Actor is allowed to alter a database table. \n                 \n                     \n                         resource  -  datasette.resources.TableResource(database, table) \n                         \n                             database  is the name of the database (string) \n                             table  is the name of the table (string)", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in actions\"]", "references": "[]"}, {"id": "authentication:actions-create-table", "page": "authentication", "ref": "actions-create-table", "title": "create-table", "content": "Actor is allowed to create a database table. \n                 \n                     \n                         resource  -  datasette.resources.DatabaseResource(database) \n                         \n                             database  is the name of the database (string)", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in actions\"]", "references": "[]"}, {"id": "authentication:actions-debug-menu", "page": "authentication", "ref": "actions-debug-menu", "title": "debug-menu", "content": "Controls if the various debug pages are displayed in the navigation menu.", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in actions\"]", "references": "[]"}, {"id": "authentication:actions-delete-row", "page": "authentication", "ref": "actions-delete-row", "title": "delete-row", "content": "Actor is allowed to delete rows from a table. \n                 \n                     \n                         resource  -  datasette.resources.TableResource(database, table) \n                         \n                             database  is the name of the database (string) \n                             table  is the name of the table (string)", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in actions\"]", "references": "[]"}, {"id": "authentication:actions-drop-table", "page": "authentication", "ref": "actions-drop-table", "title": "drop-table", "content": "Actor is allowed to drop a database table. \n                 \n                     \n                         resource  -  datasette.resources.TableResource(database, table) \n                         \n                             database  is the name of the database (string) \n                             table  is the name of the table (string)", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in actions\"]", "references": "[]"}, {"id": "authentication:actions-execute-sql", "page": "authentication", "ref": "actions-execute-sql", "title": "execute-sql", "content": "Actor is allowed to run arbitrary SQL queries against a specific database, e.g.  https://latest.datasette.io/fixtures/-/query?sql=select+100 \n                 \n                     \n                         resource  -  datasette.resources.DatabaseResource(database) \n                         \n                             database  is the name of the database (string) \n                         \n                     \n                 \n                 See also  the default_allow_sql setting .", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in actions\"]", "references": "[{\"href\": \"https://latest.datasette.io/fixtures/-/query?sql=select+100\", \"label\": \"https://latest.datasette.io/fixtures/-/query?sql=select+100\"}]"}, {"id": "authentication:actions-insert-row", "page": "authentication", "ref": "actions-insert-row", "title": "insert-row", "content": "Actor is allowed to insert rows into a table. \n                 \n                     \n                         resource  -  datasette.resources.TableResource(database, table) \n                         \n                             database  is the name of the database (string) \n                             table  is the name of the table (string)", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in actions\"]", "references": "[]"}, {"id": "authentication:actions-permissions-debug", "page": "authentication", "ref": "actions-permissions-debug", "title": "permissions-debug", "content": "Actor is allowed to view the  /-/permissions  debug tools.", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in actions\"]", "references": "[]"}, {"id": "authentication:actions-set-column-type", "page": "authentication", "ref": "actions-set-column-type", "title": "set-column-type", "content": "Actor is allowed to set assigned  column types  for columns in a table. \n                 \n                     \n                         resource  -  datasette.resources.TableResource(database, table) \n                         \n                             database  is the name of the database (string) \n                             table  is the name of the table (string)", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in actions\"]", "references": "[]"}, {"id": "authentication:actions-update-row", "page": "authentication", "ref": "actions-update-row", "title": "update-row", "content": "Actor is allowed to update rows in a table. \n                 \n                     \n                         resource  -  datasette.resources.TableResource(database, table) \n                         \n                             database  is the name of the database (string) \n                             table  is the name of the table (string)", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in actions\"]", "references": "[]"}, {"id": "authentication:actions-view-database", "page": "authentication", "ref": "actions-view-database", "title": "view-database", "content": "Actor is allowed to view a database page, e.g.  https://latest.datasette.io/fixtures \n                 \n                     \n                         resource  -  datasette.permissions.DatabaseResource(database) \n                         \n                             database  is the name of the database (string)", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in actions\"]", "references": "[{\"href\": \"https://latest.datasette.io/fixtures\", \"label\": \"https://latest.datasette.io/fixtures\"}]"}, {"id": "authentication:actions-view-database-download", "page": "authentication", "ref": "actions-view-database-download", "title": "view-database-download", "content": "Actor is allowed to download a database, e.g.  https://latest.datasette.io/fixtures.db \n                 \n                     \n                         resource  -  datasette.resources.DatabaseResource(database) \n                         \n                             database  is the name of the database (string)", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in actions\"]", "references": "[{\"href\": \"https://latest.datasette.io/fixtures.db\", \"label\": \"https://latest.datasette.io/fixtures.db\"}]"}, {"id": "authentication:actions-view-instance", "page": "authentication", "ref": "actions-view-instance", "title": "view-instance", "content": "Top level permission - Actor is allowed to view any pages within this instance, starting at  https://latest.datasette.io/", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in actions\"]", "references": "[{\"href\": \"https://latest.datasette.io/\", \"label\": \"https://latest.datasette.io/\"}]"}, {"id": "authentication:actions-view-query", "page": "authentication", "ref": "actions-view-query", "title": "view-query", "content": "Actor is allowed to view (and execute) a  canned query  page, e.g.  https://latest.datasette.io/fixtures/pragma_cache_size  - this includes executing  Writable canned queries . \n                 \n                     \n                         resource  -  datasette.resources.QueryResource(database, query) \n                         \n                             database  is the name of the database (string) \n                             query  is the name of the canned query (string)", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in actions\"]", "references": "[{\"href\": \"https://latest.datasette.io/fixtures/pragma_cache_size\", \"label\": \"https://latest.datasette.io/fixtures/pragma_cache_size\"}]"}, {"id": "authentication:actions-view-table", "page": "authentication", "ref": "actions-view-table", "title": "view-table", "content": "Actor is allowed to view a table (or view) page, e.g.  https://latest.datasette.io/fixtures/complex_foreign_keys \n                 \n                     \n                         resource  -  datasette.resources.TableResource(database, table) \n                         \n                             database  is the name of the database (string) \n                             table  is the name of the table (string)", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in actions\"]", "references": "[{\"href\": \"https://latest.datasette.io/fixtures/complex_foreign_keys\", \"label\": \"https://latest.datasette.io/fixtures/complex_foreign_keys\"}]"}, {"id": "authentication:allowdebugview", "page": "authentication", "ref": "allowdebugview", "title": "The /-/allow-debug tool", "content": "The  /-/allow-debug  tool lets you try out different   \"action\"  blocks against different  \"actor\"  JSON objects. You can try that out here:  https://latest.datasette.io/-/allow-debug", "breadcrumbs": "[\"Authentication and permissions\", \"Permissions\"]", "references": "[{\"href\": \"https://latest.datasette.io/-/allow-debug\", \"label\": \"https://latest.datasette.io/-/allow-debug\"}]"}, {"id": "authentication:allowedresourcesview", "page": "authentication", "ref": "allowedresourcesview", "title": "Allowed resources view", "content": "The  /-/allowed  endpoint displays resources that the current actor can access for a specified  action . \n                 This endpoint provides an interactive HTML form interface. Add  .json  to the URL path (e.g.  /-/allowed.json ) to get the raw JSON response instead. \n                 Pass  ?action=view-table  (or another action) to select the action. Optional  parent=  and  child=  query parameters can narrow the results to a specific database/table pair. \n                 This endpoint is publicly accessible to help users understand their own permissions. The potentially sensitive  reason  field is only shown to users with the  permissions-debug  permission - it shows the plugins and explanatory reasons that were responsible for each decision.", "breadcrumbs": "[\"Authentication and permissions\", \"Permissions debug tools\"]", "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 clients (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 clients. \n             The actor dictionary can be any shape - the design of that data structure is left up to the plugins. Actors should always include a unique  \"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: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": "[]"}, {"id": "authentication:authentication-cli-create-token", "page": "authentication", "ref": "authentication-cli-create-token", "title": "datasette create-token", "content": "You can also create tokens on the command line using the  datasette create-token  command. \n                 This command takes one required argument - the ID of the actor to be associated with the created token. \n                 You can specify a  -e/--expires-after  option in seconds. If omitted, the token will never expire. \n                 The command will sign the token using the  DATASETTE_SECRET  environment variable, if available. You can also pass the secret using the  --secret  option. \n                 This means you can run the command locally to create tokens for use with a deployed Datasette instance, provided you know that instance's secret. \n                 To create a token for the  root  actor that will expire in one hour: \n                 datasette create-token root --expires-after 3600 \n                 To create a token that never expires using a specific secret: \n                 datasette create-token root --secret my-secret-goes-here", "breadcrumbs": "[\"Authentication and permissions\", \"API Tokens\"]", "references": "[]"}, {"id": "authentication:authentication-cli-create-token-restrict", "page": "authentication", "ref": "authentication-cli-create-token-restrict", "title": "Restricting the actions that a token can perform", "content": "Tokens created using  datasette create-token ACTOR_ID  will inherit all of the permissions of the actor that they are associated with. \n                     You can pass additional options to create tokens that are restricted to a subset of that actor's permissions. \n                     To restrict the token to just specific permissions against all available databases, use the  --all  option: \n                     datasette create-token root --all insert-row --all update-row \n                     This option can be passed as many times as you like. In the above example the token will only be allowed to insert and update rows. \n                     You can also restrict permissions such that they can only be used within specific databases: \n                     datasette create-token root --database mydatabase insert-row \n                     The resulting token will only be able to insert rows, and only to tables in the  mydatabase  database. \n                     Finally, you can restrict permissions to individual resources - tables, SQL views and  named queries  - within a specific database: \n                     datasette create-token root --resource mydatabase mytable insert-row \n                     These options have short versions:  -a  for  --all ,  -d  for  --database  and  -r  for  --resource . \n                     You can add  --debug  to see a JSON representation of the token that has been created. Here's a full example: \n                     datasette create-token root \\\n    --secret mysecret \\\n    --all view-instance \\\n    --all view-table \\\n    --database docs view-query \\\n    --resource docs documents insert-row \\\n    --resource docs documents update-row \\\n    --debug \n                     This example outputs the following: \n                     dstok_.eJxFizEKgDAMRe_y5w4qYrFXERGxDkVsMI0uxbubdjFL8l_ez1jhwEQCA6Fjjxp90qtkuHawzdjYrh8MFobLxZ_wBH0_gtnAF-hpS5VfmF8D_lnd97lHqUJgLd6sls4H1qwlhA.nH_7RecYHj5qSzvjhMU95iy0Xlc\n\nDecoded:\n\n{\n  \"a\": \"root\",\n  \"token\": \"dstok\",\n  \"t\": 1670907246,\n  \"_r\": {\n    \"a\": [\n      \"vi\",\n      \"vt\"\n    ],\n    \"d\": {\n      \"docs\": [\n        \"vq\"\n      ]\n    },\n    \"r\": {\n      \"docs\": {\n        \"documents\": [\n          \"ir\",\n          \"ur\"\n        ]\n      }\n    }\n  }\n} \n                     Restrictions act as an allowlist layered on top of the actor's existing\n                        permissions. They can only remove access the actor would otherwise have\u2014they\n                        cannot grant new access. If the underlying actor is denied by  allow  rules in\n                         datasette.yaml  or by a plugin, a token that lists that resource in its\n                         \"_r\"  section will still be denied. \n                     To create tokens with restrictions in Python code, use the  TokenRestrictions  builder and pass it to  datasette.create_token() .", "breadcrumbs": "[\"Authentication and permissions\", \"API Tokens\", \"datasette create-token\"]", "references": "[]"}, {"id": "authentication:authentication-default-deny", "page": "authentication", "ref": "authentication-default-deny", "title": "Denying all permissions by default", "content": "By default, Datasette allows unauthenticated access to view databases, tables, and execute SQL queries. \n                 You may want to run Datasette in a mode where  all  access is denied by default, and you explicitly grant permissions only to authenticated users, either using the  --root mechanism  or through  configuration file rules  or plugins. \n                 Use the  --default-deny  command-line option to run Datasette in this mode: \n                 datasette --default-deny data.db --root \n                 With  --default-deny  enabled: \n                 \n                     \n                         Anonymous users are denied access to view the instance, databases, tables, and queries \n                     \n                     \n                         Authenticated users are also denied access unless they're explicitly granted permissions \n                     \n                     \n                         The root user (when using  --root ) still has access to everything \n                     \n                     \n                         You can grant permissions using  configuration file rules  or plugins \n                     \n                 \n                 For example, to allow only a specific user to access your instance: \n                 datasette --default-deny data.db --config datasette.yaml \n                 Where  datasette.yaml  contains: \n                 allow:\n  id: alice \n                 This configuration will deny access to everyone except the user with  id  of  alice .", "breadcrumbs": "[\"Authentication and permissions\", \"Permissions\"]", "references": "[]"}, {"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(\"/\")\ndatasette.set_actor_cookie(response, {\"id\": \"cleopaws\"}) \n             The shape of data encoded in the cookie is as follows: \n             {\n  \"a\": {\n    \"id\": \"cleopaws\"\n  }\n} \n             To implement logout in a plugin, use the  delete_actor_cookie()  method: \n             response = Response.redirect(\"/\")\ndatasette.delete_actor_cookie(response)", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}, {"id": "authentication:authentication-ds-actor-expiry", "page": "authentication", "ref": "authentication-ds-actor-expiry", "title": "Including an expiry time", "content": "ds_actor  cookies can optionally include a signed expiry timestamp, after which the cookies will no longer be valid. Authentication plugins may chose to use this mechanism to limit the lifetime of the cookie. For example, if a plugin implements single-sign-on against another source it may decide to set short-lived cookies so that if the user is removed from the SSO system their existing Datasette cookies will stop working shortly afterwards. \n                 To include an expiry pass  expire_after=  to  datasette.set_actor_cookie()  with a number of seconds. For example, to expire in 24 hours: \n                 response = Response.redirect(\"/\")\ndatasette.set_actor_cookie(\n    response, {\"id\": \"cleopaws\"}, expire_after=60 * 60 * 24\n) \n                 The resulting cookie will encode data that looks something like this: \n                 {\n  \"a\": {\n    \"id\": \"cleopaws\"\n  },\n  \"e\": \"1jjSji\"\n}", "breadcrumbs": "[\"Authentication and permissions\", \"The ds_actor cookie\"]", "references": "[]"}, {"id": "authentication:authentication-permissions", "page": "authentication", "ref": "authentication-permissions", "title": "Permissions", "content": "Datasette's permissions system is built around SQL queries. Datasette and its plugins construct SQL queries to resolve the list of resources that an actor cas access. \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 actions ( view-database ,  view-table  etc) are allowed by Datasette's default configuration: unless you  configure additional permission rules  unauthenticated users will be allowed to access content. \n             Other actions, including those introduced by plugins, will default to  deny .", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}, {"id": "authentication:authentication-permissions-allow", "page": "authentication", "ref": "authentication-permissions-allow", "title": "Defining permissions with \"allow\" blocks", "content": "One way to define permissions in Datasette is to use an  \"allow\"  block  in the datasette.yaml file . This is a JSON document describing which actors are allowed to perform an action against a specific resource. \n                 Each  allow  block is compiled into SQL and combined with any\n                     plugin-provided rules  to produce\n                    the cascading allow/deny decisions that power  await .allowed(*, action, resource, actor=None) . \n                 The most basic form of allow block is this ( allow demo ,  deny demo ): \n                 [[[cog\nfrom metadata_doc import config_example\nimport textwrap\nconfig_example(cog, textwrap.dedent(\n  \"\"\"\n    allow:\n      id: root\n    \"\"\").strip(),\n    \"YAML\", \"JSON\"\n  ) \n                 ]]] \n                 [[[end]]] \n                 This will match any actors with an  \"id\"  property of  \"root\"  - for example, an actor that looks like this: \n                 {\n    \"id\": \"root\",\n    \"name\": \"Root User\"\n} \n                 An allow block can specify \"deny all\" using  false  ( demo ): \n                 [[[cog\nfrom metadata_doc import config_example\nimport textwrap\nconfig_example(cog, textwrap.dedent(\n  \"\"\"\n    allow: false\n    \"\"\").strip(),\n    \"YAML\", \"JSON\"\n  ) \n                 ]]] \n                 [[[end]]] \n                 An  \"allow\"  of  true  allows all access ( demo ): \n                 [[[cog\nfrom metadata_doc import config_example\nimport textwrap\nconfig_example(cog, textwrap.dedent(\n  \"\"\"\n    allow: true\n    \"\"\").strip(),\n    \"YAML\", \"JSON\"\n  ) \n                 ]]] \n                 [[[end]]] \n                 Allow keys can provide a list of values. These will match any actor that has any of those values ( allow demo ,  deny demo ): \n                 [[[cog\nfrom metadata_doc import config_example\nimport textwrap\nconfig_example(cog, textwrap.dedent(\n  \"\"\"\n    allow:\n      id:\n      - simon\n      - cleopaws\n    \"\"\").strip(),\n    \"YAML\", \"JSON\"\n  ) \n                 ]]] \n                 [[[end]]] \n                 This will match any actor with an  \"id\"  of either  \"simon\"  or  \"cleopaws\" . \n                 Actors can have properties that feature a list of values. These will be matched against the list of values in an allow block. Consider the following actor: \n                 {\n    \"id\": \"simon\",\n    \"roles\": [\"staff\", \"developer\"]\n} \n                 This allow block will provide access to any actor that has  \"developer\"  as one of their roles ( allow demo ,  deny demo ): \n                 [[[cog\nfrom metadata_doc import config_example\nimport textwrap\nconfig_example(cog, textwrap.dedent(\n  \"\"\"\n    allow:\n      roles:\n      - developer\n    \"\"\").strip(),\n    \"YAML\", \"JSON\"\n  ) \n                 ]]] \n                 [[[end]]] \n                 Note that \"roles\" is not a concept that is baked into Datasette - it's a convention that plugins can choose to implement and act on. \n                 If you want to provide access to any actor with a value for a specific key, use  \"*\" . For example, to match any logged-in user specify the following ( allow demo ,  deny demo ): \n                 [[[cog\nfrom metadata_doc import config_example\nimport textwrap\nconfig_example(cog, textwrap.dedent(\n  \"\"\"\n    allow:\n      id: \"*\"\n    \"\"\").strip(),\n    \"YAML\", \"JSON\"\n  ) \n                 ]]] \n                 [[[end]]] \n                 You can specify that only unauthenticated actors (from anonymous HTTP requests) should be allowed access using the special  \"unauthenticated\": true  key in an allow block ( allow demo ,  deny demo ): \n                 [[[cog\nfrom metadata_doc import config_example\nimport textwrap\nconfig_example(cog, textwrap.dedent(\n  \"\"\"\n    allow:\n      unauthenticated: true\n    \"\"\").strip(),\n    \"YAML\", \"JSON\"\n  ) \n                 ]]] \n                 [[[end]]] \n                 Allow keys act as an \"or\" mechanism. An actor will be able to execute the query if any of their JSON properties match any of the values in the corresponding lists in the  allow  block. The following block will allow users with either a  role  of  \"ops\"  OR users who have an  id  of  \"simon\"  or  \"cleopaws\" : \n                 [[[cog\nfrom metadata_doc import config_example\nimport textwrap\nconfig_example(cog, textwrap.dedent(\n  \"\"\"\n    allow:\n      id:\n      - simon\n      - cleopaws\n      role: ops\n    \"\"\").strip(),\n    \"YAML\", \"JSON\"\n  ) \n                 ]]] \n                 [[[end]]] \n                 Demo for cleopaws ,  demo for ops role ,  demo for an actor matching neither rule .", "breadcrumbs": "[\"Authentication and permissions\", \"Permissions\"]", "references": "[{\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%22id%22%3A+%22root%22%7D&allow=%7B%0D%0A++++++++%22id%22%3A+%22root%22%0D%0A++++%7D\", \"label\": \"allow demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%22id%22%3A+%22trevor%22%7D&allow=%7B%0D%0A++++++++%22id%22%3A+%22root%22%0D%0A++++%7D\", \"label\": \"deny demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22root%22%0D%0A%7D&allow=false\", \"label\": \"demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22root%22%0D%0A%7D&allow=true\", \"label\": \"demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22cleopaws%22%0D%0A%7D&allow=%7B%0D%0A++++%22id%22%3A+%5B%0D%0A++++++++%22simon%22%2C%0D%0A++++++++%22cleopaws%22%0D%0A++++%5D%0D%0A%7D\", \"label\": \"allow demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22pancakes%22%0D%0A%7D&allow=%7B%0D%0A++++%22id%22%3A+%5B%0D%0A++++++++%22simon%22%2C%0D%0A++++++++%22cleopaws%22%0D%0A++++%5D%0D%0A%7D\", \"label\": \"deny demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22simon%22%2C%0D%0A++++%22roles%22%3A+%5B%0D%0A++++++++%22staff%22%2C%0D%0A++++++++%22developer%22%0D%0A++++%5D%0D%0A%7D&allow=%7B%0D%0A++++%22roles%22%3A+%5B%0D%0A++++++++%22developer%22%0D%0A++++%5D%0D%0A%7D\", \"label\": \"allow demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22cleopaws%22%2C%0D%0A++++%22roles%22%3A+%5B%22dog%22%5D%0D%0A%7D&allow=%7B%0D%0A++++%22roles%22%3A+%5B%0D%0A++++++++%22developer%22%0D%0A++++%5D%0D%0A%7D\", \"label\": \"deny demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22simon%22%0D%0A%7D&allow=%7B%0D%0A++++%22id%22%3A+%22*%22%0D%0A%7D\", \"label\": \"allow demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22bot%22%3A+%22readme-bot%22%0D%0A%7D&allow=%7B%0D%0A++++%22id%22%3A+%22*%22%0D%0A%7D\", \"label\": \"deny demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=null&allow=%7B%0D%0A++++%22unauthenticated%22%3A+true%0D%0A%7D\", \"label\": \"allow demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22hello%22%0D%0A%7D&allow=%7B%0D%0A++++%22unauthenticated%22%3A+true%0D%0A%7D\", \"label\": \"deny demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22cleopaws%22%0D%0A%7D&allow=%7B%0D%0A++++%22id%22%3A+%5B%0D%0A++++++++%22simon%22%2C%0D%0A++++++++%22cleopaws%22%0D%0A++++%5D%2C%0D%0A++++%22role%22%3A+%22ops%22%0D%0A%7D\", \"label\": \"Demo for cleopaws\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22trevor%22%2C%0D%0A++++%22role%22%3A+%5B%0D%0A++++++++%22ops%22%2C%0D%0A++++++++%22staff%22%0D%0A++++%5D%0D%0A%7D&allow=%7B%0D%0A++++%22id%22%3A+%5B%0D%0A++++++++%22simon%22%2C%0D%0A++++++++%22cleopaws%22%0D%0A++++%5D%2C%0D%0A++++%22role%22%3A+%22ops%22%0D%0A%7D\", \"label\": \"demo for ops role\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22percy%22%2C%0D%0A++++%22role%22%3A+%5B%0D%0A++++++++%22staff%22%0D%0A++++%5D%0D%0A%7D&allow=%7B%0D%0A++++%22id%22%3A+%5B%0D%0A++++++++%22simon%22%2C%0D%0A++++++++%22cleopaws%22%0D%0A++++%5D%2C%0D%0A++++%22role%22%3A+%22ops%22%0D%0A%7D\", \"label\": \"demo for an actor matching neither rule\"}]"}, {"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 has permission to view a table they will be able to view that table, independent of if they have permission to view the database or instance that the table exists within.", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}, {"id": "authentication:authentication-permissions-database", "page": "authentication", "ref": "authentication-permissions-database", "title": "Access to specific databases", "content": "To limit access to a specific  private.db  database to just authenticated users, use the  \"allow\"  block like this: \n                 [[[cog\nconfig_example(cog, \"\"\"\n    databases:\n      private:\n        allow:\n          id: \"*\"\n\"\"\") \n                 ]]] \n                 [[[end]]]", "breadcrumbs": "[\"Authentication and permissions\", \"Access permissions in \"]", "references": "[]"}, {"id": "authentication:authentication-permissions-execute-sql", "page": "authentication", "ref": "authentication-permissions-execute-sql", "title": "Controlling the ability to execute arbitrary SQL", "content": "Datasette defaults to allowing any site visitor to execute their own custom SQL queries, for example using the form on  the database page  or by appending a  ?_where=  parameter to the table page  like this . \n                 Access to this ability is controlled by the  execute-sql  permission. \n                 The easiest way to disable arbitrary SQL queries is using the  default_allow_sql setting  when you first start Datasette running. \n                 You can alternatively use an  \"allow_sql\"  block to control who is allowed to execute arbitrary SQL queries. \n                 To prevent any user from executing arbitrary SQL queries, use this: \n                 [[[cog\nconfig_example(cog, \"\"\"\n    allow_sql: false\n\"\"\") \n                 ]]] \n                 [[[end]]] \n                 To enable just the  root user  to execute SQL for all databases in your instance, use the following: \n                 [[[cog\nconfig_example(cog, \"\"\"\n    allow_sql:\n      id: root\n\"\"\") \n                 ]]] \n                 [[[end]]] \n                 To limit this ability for just one specific database, use this: \n                 [[[cog\nconfig_example(cog, \"\"\"\n    databases:\n      mydatabase:\n        allow_sql:\n          id: root\n\"\"\") \n                 ]]] \n                 [[[end]]]", "breadcrumbs": "[\"Authentication and permissions\", \"Access permissions in \"]", "references": "[{\"href\": \"https://latest.datasette.io/fixtures\", \"label\": \"the database page\"}, {\"href\": \"https://latest.datasette.io/fixtures/facetable?_where=_city_id=1\", \"label\": \"like this\"}]"}, {"id": "authentication:authentication-permissions-explained", "page": "authentication", "ref": "authentication-permissions-explained", "title": "How permissions are resolved", "content": "Datasette performs permission checks using the internal  await .allowed(*, action, resource, actor=None) , method which accepts keyword arguments for  action ,  resource  and an optional  actor . \n                 resource  should be an instance of the appropriate  Resource  subclass from  datasette.resources \u2014for example  InstanceResource() ,  DatabaseResource(database=\"... )`` or  TableResource(database=\"...\", table=\"...\") . This defaults to  InstanceResource()  if not specified. \n                 When a check runs Datasette gathers allow/deny rules from multiple sources and\n                    compiles them into a SQL query. The resulting query describes all of the\n                    resources an actor may access for that action, together with the reasons those\n                    resources were allowed or denied. The combined sources are: \n                 \n                     \n                         allow  blocks configured in  datasette.yaml . \n                     \n                     \n                         Actor restrictions  encoded into the actor dictionary or API token. \n                     \n                     \n                         The \"root\" user shortcut when  --root  (or  Datasette.root_enabled ) is active, replying  True  to all permission chucks unless configuration rules deny them at a more specific level. \n                     \n                     \n                         Any additional SQL provided by plugins implementing  permission_resources_sql(datasette, actor, action) . \n                     \n                 \n                 Datasette evaluates the SQL to determine if the requested  resource  is\n                    included. Explicit deny rules returned by configuration or plugins will block\n                    access even if other rules allowed it.", "breadcrumbs": "[\"Authentication and permissions\", \"Permissions\"]", "references": "[]"}, {"id": "authentication:authentication-permissions-instance", "page": "authentication", "ref": "authentication-permissions-instance", "title": "Access to an instance", "content": "Here's how to restrict access to your entire Datasette instance to just the  \"id\": \"root\"  user: \n                 [[[cog\nfrom metadata_doc import config_example\nconfig_example(cog, \"\"\"\n    title: My private Datasette instance\n    allow:\n      id: root\n  \"\"\") \n                 ]]] \n                 [[[end]]] \n                 To deny access to all users, you can use  \"allow\": false : \n                 [[[cog\nconfig_example(cog, \"\"\"\n    title: My entirely inaccessible instance\n    allow: false\n\"\"\") \n                 ]]] \n                 [[[end]]] \n                 One reason to do this is if you are using a Datasette plugin - such as  datasette-permissions-sql  - to control permissions instead.", "breadcrumbs": "[\"Authentication and permissions\", \"Access permissions in \"]", "references": "[{\"href\": \"https://github.com/simonw/datasette-permissions-sql\", \"label\": \"datasette-permissions-sql\"}]"}, {"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             Other table-scoped write permissions, including  set-column-type , can be configured in the same place. \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-query", "page": "authentication", "ref": "authentication-permissions-query", "title": "Access to specific canned queries", "content": "Canned queries  allow you to configure named SQL queries in your  datasette.yaml  that can be executed by users. These queries can be set up to both read and write to the database, so controlling who can execute them can be important. \n                 To limit access to the  add_name  canned query in your  dogs.db  database to just the  root user : \n                 [[[cog\nconfig_example(cog, \"\"\"\n    databases:\n      dogs:\n        queries:\n          add_name:\n            sql: INSERT INTO names (name) VALUES (:name)\n            write: true\n            allow:\n              id:\n              - root\n\"\"\") \n                 ]]] \n                 [[[end]]]", "breadcrumbs": "[\"Authentication and permissions\", \"Access permissions in \"]", "references": "[]"}, {"id": "authentication:authentication-permissions-table", "page": "authentication", "ref": "authentication-permissions-table", "title": "Access to specific tables and views", "content": "To limit access to the  users  table in your  bakery.db  database: \n                 [[[cog\nconfig_example(cog, \"\"\"\n    databases:\n      bakery:\n        tables:\n          users:\n            allow:\n              id: '*'\n\"\"\") \n                 ]]] \n                 [[[end]]] \n                 This works for SQL views as well - you can list their names in the  \"tables\"  block above in the same way as regular tables. \n                 \n                     Restricting access to tables and views in this way will NOT prevent users from querying them using arbitrary SQL queries,  like this  for example. \n                     If you are restricting access to specific tables you should also use the  \"allow_sql\"  block to prevent users from bypassing the limit with their own SQL queries - see  Controlling the ability to execute arbitrary SQL .", "breadcrumbs": "[\"Authentication and permissions\", \"Access permissions in \"]", "references": "[{\"href\": \"https://latest.datasette.io/fixtures?sql=select+*+from+facetable\", \"label\": \"like this\"}]"}, {"id": "authentication:authentication-root", "page": "authentication", "ref": "authentication-root", "title": "Using the \"root\" actor", "content": "Datasette currently leaves almost all forms of authentication to plugins -  datasette-auth-github  for example. \n                 The one exception is the \"root\" account, which you can sign into while using Datasette on your local machine. The root user has  all permissions  - they can perform any action regardless of other permission rules. \n                 The  --root  flag is designed for local development and testing. When you start Datasette with  --root , the root user automatically receives every permission, including: \n                 \n                     \n                         All view permissions ( view-instance ,  view-database ,  view-table , etc.) \n                     \n                     \n                         All write permissions ( insert-row ,  update-row ,  delete-row ,  create-table ,  alter-table ,  set-column-type ,  drop-table ) \n                     \n                     \n                         Debug permissions ( permissions-debug ,  debug-menu ) \n                     \n                     \n                         Any custom permissions defined by plugins \n                     \n                 \n                 If you add explicit deny rules in  datasette.yaml  those can still block the\n                    root actor from specific databases or tables. \n                 The  --root  flag sets an internal  root_enabled  switch\u2014without it, a signed-in user with  {\"id\": \"root\"}  is treated like any other actor. \n                 To sign in as root, start Datasette using the  --root  command-line option, like this: \n                 datasette --root \n                 Datasette will output a single-use-only login URL on startup: \n                 http://127.0.0.1:8001/-/auth-token?token=786fc524e0199d70dc9a581d851f466244e114ca92f33aa3b42a139e9388daa7\nINFO:     Started server process [25801]\nINFO:     Waiting for application startup.\nINFO:     Application startup complete.\nINFO:     Uvicorn running on http://127.0.0.1:8001 (Press CTRL+C to quit) \n                 Click on that link and then visit  http://127.0.0.1:8001/-/actor  to confirm that you are authenticated as an actor that looks like this: \n                 {\n    \"id\": \"root\"\n}", "breadcrumbs": "[\"Authentication and permissions\", \"Actors\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette-auth-github\", \"label\": \"datasette-auth-github\"}]"}, {"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:logoutview", "page": "authentication", "ref": "logoutview", "title": "The /-/logout page", "content": "The page at  /-/logout  provides the ability to log out of a  ds_actor  cookie authentication session.", "breadcrumbs": "[\"Authentication and permissions\", \"The ds_actor cookie\"]", "references": "[]"}, {"id": "authentication:permissioncheckview", "page": "authentication", "ref": "permissioncheckview", "title": "Permission check view", "content": "The  /-/check  endpoint evaluates a single action/resource pair and returns information indicating whether the access was allowed along with diagnostic information. \n                 This endpoint provides an interactive HTML form interface. Add  .json  to the URL path (e.g.  /-/check.json?action=view-instance ) to get the raw JSON response instead. \n                 Pass  ?action=  to specify the action to check, and optional  ?parent=  and  ?child=  parameters to specify the resource.", "breadcrumbs": "[\"Authentication and permissions\", \"Permissions debug tools\"]", "references": "[]"}, {"id": "authentication:permissionrulesview", "page": "authentication", "ref": "permissionrulesview", "title": "Permission rules view", "content": "The  /-/rules  endpoint displays all permission rules (both allow and deny) for each candidate resource for the requested action. \n                 This endpoint provides an interactive HTML form interface. Add  .json  to the URL path (e.g.  /-/rules.json?action=view-table ) to get the raw JSON response instead. \n                 Pass  ?action=  as a query parameter to specify which action to check. \n                 This endpoint requires the  permissions-debug  permission.", "breadcrumbs": "[\"Authentication and permissions\", \"Permissions debug tools\"]", "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  await .allowed(*, action, resource, actor=None) \u2014for example: \n             from datasette.resources import TableResource\n\ncan_edit = await datasette.allowed(\n    action=\"update-row\",\n    resource=TableResource(database=\"fixtures\", table=\"facetable\"),\n    actor=request.actor,\n) \n             Use  await .ensure_permission(action, resource=None, actor=None)  when you need to enforce a permission and\n                raise a  Forbidden  error automatically. \n             Plugins that define new operations should return  Action \n                objects from  register_actions(datasette)  and can supply additional allow/deny\n                rules by returning  PermissionSQL  objects from the\n                 permission_resources_sql(datasette, actor, action)  hook. Those rules are merged with\n                configuration  allow  blocks and actor restrictions to determine the final\n                result for each check.", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}, {"id": "authentication:permissionsdebugview", "page": "authentication", "ref": "permissionsdebugview", "title": "Permissions debug tools", "content": "The debug tool at  /-/permissions  is available to any actor with the  permissions-debug  permission. By default this is just the  authenticated root user  but you can open it up to all users by starting Datasette like this: \n             datasette -s permissions.permissions-debug true data.db \n             The page shows the 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": "[]"}], "truncated": false}