Q:

Google API - DocumentList - Create a shared link

Using the Document List API v3.0, I'm already creating a document. But now I want to share it privately using a shared link.
The protocol guide indicate that I should build a POST request like this one:
POST /feeds/default/private/full/<resource_id>/acl
GData-Version: 3.0
Authorization: OAuth <access_token>

<entry xmlns="http://www.w3.org/2005/Atom" xmlns:gAcl='http://schemas.google.com/acl/2007'>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://schemas.google.com/acl/2007#accessRule'/>
  <gAcl:role value='writer'/>
  <gAcl:scope type='user' value='new_writer@example.com'/>
</entry>

But I have a problem with the Scope. The guide list 4 of them:

user — a user's email address. => I want a link, I don't even know the email address of the person who'll access the document at the end of the process.
group — a Google Group email address. => I use no group.
domain — a Google Apps domain. => I use no domain.
default — publicly shared with all users. => I don't want the document to be public.

So what scope should I use to have a private document accessible with a sharing link ?

A:

From what I've understood yet, I need to use the default scope, and then restrict the role to a specific key.
POST /feeds/default/private/full/<resource_id>/acl
GData-Version: 3.0
Authorization: OAuth <access_token>

<entry xmlns='http://www.w3.org/2005/Atom' xmlns:gAcl='http://schemas.google.com/acl/2007'>
<category scheme='http://schemas.google.com/g/2005#kind'
 term='http://schemas.google.com/acl/2007#accessRule'/>
  <gAcl:withKey key='dummy_key'>
     <gAcl:role value='writer'/>
  </gAcl:withKey>
  <gAcl:scope type='default'/>
</entry>

The Google API Documentation doesn't explain at all what's supposed to go in the key attribute. But the good news is that I just put a random string and the file apear to be accessible with the shared link, without beeing accessible to the whole public.
The document is now accessible with the following URL:
https://docs.google.com/document/d/<untyped_ressource_id>/edit?hl=en_GB

For the reccord, if I wanted to have the document accessible to the public ( referenced, etc. ) I would simply remove the withKey Part:
POST /feeds/default/private/full/<resource_id>/acl
GData-Version: 3.0
Authorization: OAuth <access_token>

<entry xmlns='http://www.w3.org/2005/Atom' xmlns:gAcl='http://schemas.google.com/acl/2007'>
<category scheme='http://schemas.google.com/g/2005#kind'
 term='http://schemas.google.com/acl/2007#accessRule'/>
  <gAcl:role value='writer'/>
  <gAcl:scope type='default'/>
</entry>

