id,page,ref,title,content,breadcrumbs,references
authentication:actions,authentication,actions,Built-in actions,"This section lists all of the permission checks that are carried out by Datasette core, along with the  resource  if it was passed.","[""Authentication and permissions""]",[]
authentication:authentication-actor,authentication,authentication-actor,Actors,"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. 
             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. 
             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. 
             Plugins can use the  actor_from_request(datasette, request)  hook to implement custom logic for authenticating an actor based on the incoming HTTP request.","[""Authentication and permissions""]",[]
authentication:authentication-actor-matches-allow,authentication,authentication-actor-matches-allow,actor_matches_allow(),"Plugins that wish to implement this same  ""allow""  block permissions scheme can take advantage of the  datasette.utils.actor_matches_allow(actor, allow)  function: 
             from datasette.utils import actor_matches_allow

actor_matches_allow({""id"": ""root""}, {""id"": ""*""})
# returns True 
             The currently authenticated actor is made available to plugins as  request.actor .","[""Authentication and permissions""]",[]
authentication:authentication-ds-actor,authentication,authentication-ds-actor,The ds_actor cookie,"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. 
             Authentication plugins can set signed  ds_actor  cookies themselves like so: 
             response = Response.redirect(""/"")
datasette.set_actor_cookie(response, {""id"": ""cleopaws""}) 
             The shape of data encoded in the cookie is as follows: 
             {
  ""a"": {
    ""id"": ""cleopaws""
  }
} 
             To implement logout in a plugin, use the  delete_actor_cookie()  method: 
             response = Response.redirect(""/"")
datasette.delete_actor_cookie(response)","[""Authentication and permissions""]",[]
authentication:authentication-permissions,authentication,authentication-permissions,Permissions,"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. 
             The key question the permissions system answers is this: 
             
                 Is this  actor  allowed to perform this  action , optionally against this particular  resource ? 
             
             Actors  are  described above . 
             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 . 
             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. 
             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. 
             Other actions, including those introduced by plugins, will default to  deny .","[""Authentication and permissions""]",[]
authentication:authentication-permissions-config,authentication,authentication-permissions-config,Access permissions in ,"There are two ways to configure permissions using  datasette.yaml  (or  datasette.json ). 
             For simple visibility permissions you can use  ""allow""  blocks in the root, database, table and query sections. 
             For other permissions you can use a  ""permissions""  block, described  in the next section . 
             You can limit who is allowed to view different parts of your Datasette instance using  ""allow""  keys in your  Configuration . 
             You can control the following: 
             
                 
                     Access to the entire Datasette instance 
                 
                 
                     Access to specific databases 
                 
                 
                     Access to specific tables and views 
                 
                 
                     Access to specific  Canned queries 
                 
             
             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.","[""Authentication and permissions""]",[]
authentication:authentication-permissions-other,authentication,authentication-permissions-other,Other permissions in ,"For all other permissions, you can use one or more  ""permissions""  blocks in your  datasette.yaml  configuration file. 
             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: 
             [[[cog
config_example(cog, """"""
    permissions:
      debug-menu:
        id: '*'
"""""") 
             ]]] 
             [[[end]]] 
             To grant  create-table  to the user with  id  of  editor  for the  docs  database: 
             [[[cog
config_example(cog, """"""
    databases:
      docs:
        permissions:
          create-table:
            id: editor
"""""") 
             ]]] 
             [[[end]]] 
             Other table-scoped write permissions, including  set-column-type , can be configured in the same place. 
             And for  insert-row  against the  reports  table in that  docs  database: 
             [[[cog
config_example(cog, """"""
    databases:
      docs:
        tables:
          reports:
            permissions:
              insert-row:
                id: editor
"""""") 
             ]]] 
             [[[end]]] 
             The  permissions debug tool  can be useful for helping test permissions that you have configured in this way.","[""Authentication and permissions""]",[]
authentication:createtokenview,authentication,createtokenview,API Tokens,"Datasette includes a default mechanism for generating API tokens that can be used to authenticate requests. 
             Authenticated users can create new API tokens using a form on the  /-/create-token  page. 
             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. 
             Created tokens can then be passed in the  Authorization: Bearer $token  header of HTTP requests to Datasette. 
             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. 
             When one of these a token accompanies a request, the actor for that request will have the following shape: 
             {
    ""id"": ""user_id"",
    ""token"": ""dstok"",
    ""token_expires"": 1667717426
} 
             The  ""id""  field duplicates the ID of the actor who first created the token. 
             The  ""token""  field identifies that this actor was authenticated using a Datasette signed token ( dstok ). 
             The  ""token_expires""  field, if present, indicates that the token will expire after that integer timestamp. 
             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. 
             Datasette plugins that implement their own form of API token authentication should follow this convention. 
             You can disable the signed token feature entirely using the  allow_signed_tokens  setting.","[""Authentication and permissions""]",[]
authentication:permissions-plugins,authentication,permissions-plugins,Checking permissions in plugins,"Datasette plugins can check if an actor has permission to perform an action using  await .allowed(*, action, resource, actor=None) —for example: 
             from datasette.resources import TableResource

can_edit = await datasette.allowed(
    action=""update-row"",
    resource=TableResource(database=""fixtures"", table=""facetable""),
    actor=request.actor,
) 
             Use  await .ensure_permission(action, resource=None, actor=None)  when you need to enforce a permission and
                raise a  Forbidden  error automatically. 
             Plugins that define new operations should return  Action 
                objects from  register_actions(datasette)  and can supply additional allow/deny
                rules by returning  PermissionSQL  objects from the
                 permission_resources_sql(datasette, actor, action)  hook. Those rules are merged with
                configuration  allow  blocks and actor restrictions to determine the final
                result for each check.","[""Authentication and permissions""]",[]
authentication:permissionsdebugview,authentication,permissionsdebugview,Permissions debug tools,"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: 
             datasette -s permissions.permissions-debug true data.db 
             The page shows the permission checks that have been carried out by the Datasette instance. 
             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. 
             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.","[""Authentication and permissions""]",[]